ultimate-brain 0.0.0-stage → 0.1.1

package/dist/commands/index.js

@@ -0,0 +1,58 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { atomicWriteFile } from "../lib/fs-safe.js";
+import { buildIndex } from "../lib/index-builder.js";
+import { scanNotes } from "../lib/notes.js";
+/** `brain index [--check]` (spec/cli.md §5.8, spec/schema.md §13). */
+export const indexCommand = {
+    name: "index",
+    usage: "brain index [--check] [--json]",
+    summary: "Regenerate index.md from note frontmatter. --check writes nothing and exits 1 if index.md is out of date.",
+    options: { check: "boolean" },
+    maxPositionals: 0,
+    needsBrain: true,
+    async run({ args, brain }) {
+        const root = brain.root;
+        const check = args.options.check === true;
+        const { notes, problems } = await scanNotes(root);
+        const built = buildIndex(notes);
+        const warnings = [
+            ...problems.map((problem) => ({ code: problem.code, message: `${problem.path}: ${problem.message}`, path: problem.path })),
+            ...built.duplicates.map((duplicate) => ({
+                code: "DUPLICATE_ID",
+                message: `${duplicate.id} in ${duplicate.path} is also in ${duplicate.kept}; kept ${duplicate.kept}`,
+                path: duplicate.path,
+                id: duplicate.id,
+            })),
+        ];
+        let current;
+        try {
+            current = await readFile(join(root, "index.md"), "utf8");
+        }
+        catch {
+            current = null;
+        }
+        const differs = current !== built.markdown;
+        const written = !check && differs;
+        if (written)
+            await atomicWriteFile(root, "index.md", built.markdown);
+        // `stale`: index.md is out of date after this command (only possible with --check).
+        const stale = check && differs;
+        const human = check
+            ? differs ? "index.md is out of date (run brain index)\n" : "index.md is current\n"
+            : written ? `index.md updated (${built.entries.length} notes)\n` : "index.md already current\n";
+        return {
+            data: {
+                written,
+                stale,
+                path: "index.md",
+                counts: built.counts,
+                notes: built.entries,
+                backlinks: built.backlinks,
+            },
+            warnings,
+            exitCode: check && stale ? 1 : 0,
+            human,
+        };
+    },
+};

package/dist/commands/init.js

@@ -0,0 +1,233 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { lstat, mkdir, readdir, readFile, realpath } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { BrainError } from "../lib/errors.js";
+import { atomicWriteFile, ensureDirectory } from "../lib/fs-safe.js";
+import { buildIndex } from "../lib/index-builder.js";
+import { isProductRepository } from "../lib/brain-path.js";
+import { appendLog } from "../lib/log.js";
+import { scanNotes } from "../lib/notes.js";
+import { listShippedSkillFiles } from "../lib/skills.js";
+const exec = promisify(execFile);
+const TEMPLATE_ROOT = fileURLToPath(new URL("../../templates/brain/", import.meta.url));
+/** `brain init <path>` (spec/cli.md §5.1). */
+export const initCommand = {
+    name: "init",
+    usage: "brain init <path> [--owner <name>] [--force] [--no-git] [--set-default] [--json]",
+    summary: "Create a new Ultimate Brain repository from the versioned template.",
+    options: { owner: "string", force: "boolean", "no-git": "boolean", "set-default": "boolean" },
+    maxPositionals: 1,
+    needsBrain: false,
+    async run({ args, now, environment }) {
+        const [requested] = args.positionals;
+        if (requested === undefined)
+            throw new BrainError("USAGE", "brain init needs a target path");
+        const target = resolve(requested);
+        const present = await inspectTarget(target);
+        if (present.kind === "file")
+            throw new BrainError("TARGET_NOT_EMPTY", `Brain target is not a directory: ${target}`);
+        if (!present.exists)
+            await mkdir(target, { recursive: true });
+        const root = await realpath(target);
+        if (await isProductRepository(root)) {
+            throw new BrainError("BRAIN_IS_PRODUCT_REPO", `Refusing to initialize the Ultimate Brain product repository: ${root}`);
+        }
+        if (await exists(join(root, "brain.json"))) {
+            throw new BrainError("ALREADY_A_BRAIN", `Target already contains brain.json: ${root}`);
+        }
+        if (present.entries.length > 0 && args.options.force !== true) {
+            throw new BrainError("TARGET_NOT_EMPTY", `Brain target is not empty: ${root}`);
+        }
+        const owner = args.options.owner ?? await defaultOwner();
+        if (owner.trim() === "")
+            throw new BrainError("USAGE", "--owner must not be empty");
+        const created = [];
+        const skipped = [];
+        const template = await listTemplateFiles();
+        for (const file of template) {
+            if (await exists(join(root, file.relative))) {
+                skipped.push(file.relative);
+                continue;
+            }
+            let content = await readFile(file.source, "utf8");
+            if (file.relative === "brain.json")
+                content = initialConfig(content, owner);
+            await ensureDirectory(root, dirname(file.relative));
+            await atomicWriteFile(root, file.relative, content);
+            created.push(file.relative);
+        }
+        // Product-owned Codex skills (decision 0029); like template files, existing ones are never overwritten.
+        for (const skill of await listShippedSkillFiles()) {
+            const path = `.agents/skills/${skill.relative}`;
+            if (await exists(join(root, path))) {
+                skipped.push(path);
+                continue;
+            }
+            await ensureDirectory(root, dirname(path));
+            await atomicWriteFile(root, path, skill.content);
+            created.push(path);
+        }
+        // The template includes an empty index, but build it rather than trusting that snapshot.
+        // With --force an existing index is left untouched along with every other existing template file.
+        if (!skipped.includes("index.md")) {
+            const { notes } = await scanNotes(root);
+            const index = buildIndex(notes).markdown;
+            await atomicWriteFile(root, "index.md", index);
+        }
+        const logPath = `log/${now.toISOString().slice(0, 7)}.md`;
+        const hadLog = await exists(join(root, logPath));
+        await appendLog(root, now, [{ op: "init", id: "-", title: owner, pairs: [["schema", 1]] }]);
+        if (!hadLog)
+            created.push(logPath);
+        const warnings = [];
+        const git = await initializeGit(root, args.options["no-git"] === true, warnings);
+        let defaultConfig;
+        if (args.options["set-default"] === true) {
+            defaultConfig = await writeDefaultConfig(root, environment.homeDirectory);
+        }
+        else {
+            defaultConfig = { written: false, path_abs: null, previous: null };
+        }
+        created.sort(comparePath);
+        skipped.sort(comparePath);
+        return {
+            resolvedBrain: root,
+            warnings,
+            data: {
+                path_abs: root,
+                created,
+                skipped,
+                git,
+                default_config: defaultConfig,
+            },
+            human: `Initialized Ultimate Brain at ${root}\n`,
+        };
+    },
+};
+async function inspectTarget(target) {
+    try {
+        const metadata = await lstat(target);
+        if (!metadata.isDirectory())
+            return { exists: true, kind: "file", entries: [] };
+        return { exists: true, kind: "directory", entries: await readdir(target) };
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return { exists: false, kind: "directory", entries: [] };
+        throw error;
+    }
+}
+async function listTemplateFiles() {
+    const root = await realpath(TEMPLATE_ROOT);
+    const files = [];
+    async function visit(folder) {
+        for (const entry of await readdir(folder, { withFileTypes: true })) {
+            const source = join(folder, entry.name);
+            if (entry.isSymbolicLink())
+                throw new BrainError("OUTSIDE_ROOT", `Template contains a symbolic link: ${source}`);
+            if (entry.isDirectory())
+                await visit(source);
+            else if (entry.isFile()) {
+                const actual = await realpath(source);
+                assertInside(root, actual);
+                const templatePath = relative(root, actual).split(sep).join("/");
+                files.push({ source: actual, relative: templatePath === "gitignore" ? ".gitignore" : templatePath });
+            }
+        }
+    }
+    await visit(root);
+    return files.sort((left, right) => comparePath(left.relative, right.relative));
+}
+function initialConfig(template, owner) {
+    let config;
+    try {
+        config = JSON.parse(template);
+    }
+    catch (error) {
+        throw new BrainError("INTERNAL", `Brain template has invalid brain.json: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isRecord(config) || !isRecord(config.owner))
+        throw new BrainError("INTERNAL", "Brain template has no owner configuration");
+    config.schema_version = 1;
+    config.owner.name = owner;
+    return `${JSON.stringify(config, null, 2)}\n`;
+}
+async function defaultOwner() {
+    try {
+        const { stdout } = await exec("git", ["config", "--get", "user.name"]);
+        const name = stdout.trim();
+        return name === "" ? "Owner" : name;
+    }
+    catch {
+        return "Owner";
+    }
+}
+async function initializeGit(root, noGit, warnings) {
+    if (noGit)
+        return { initialized: false, committed: false };
+    try {
+        await exec("git", ["init"], { cwd: root });
+        await exec("git", ["add", "--all"], { cwd: root });
+    }
+    catch {
+        warnings.push({ code: "GIT_COMMIT_SKIPPED", message: "Git initialization or staging failed; brain files were kept." });
+        return { initialized: false, committed: false };
+    }
+    try {
+        await exec("git", ["commit", "-m", "init: ultimate brain (schema v1)"], { cwd: root });
+        return { initialized: true, committed: true };
+    }
+    catch {
+        warnings.push({ code: "GIT_COMMIT_SKIPPED", message: "Git commit was skipped; configure a Git identity and commit the brain files." });
+        return { initialized: true, committed: false };
+    }
+}
+async function writeDefaultConfig(brain, homeDirectory) {
+    // `homeDirectory` is injectable for isolated CLI tests; production uses the current user's home.
+    const home = homeDirectory ?? process.env.HOME;
+    if (home === undefined || home === "")
+        throw new BrainError("INTERNAL", "Cannot determine home directory for --set-default");
+    const absoluteHome = resolve(home);
+    const root = await realpath(absoluteHome);
+    const folder = join(root, ".config", "ultimate-brain");
+    await ensureDirectory(root, ".config/ultimate-brain");
+    const configPath = join(folder, "config.json");
+    let previous = null;
+    try {
+        previous = JSON.parse(await readFile(configPath, "utf8"));
+    }
+    catch (error) {
+        if (!isNodeError(error) || error.code !== "ENOENT")
+            previous = "<unreadable>";
+    }
+    await atomicWriteFile(root, configPath, `${JSON.stringify({ brain }, null, 2)}\n`);
+    return { written: true, path_abs: configPath, previous };
+}
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function assertInside(root, target) {
+    const path = relative(root, target);
+    if (path === ".." || path.startsWith(`..${sep}`)) {
+        throw new BrainError("OUTSIDE_ROOT", `Template file resolves outside its root: ${target}`);
+    }
+}
+function comparePath(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/commands/link.js

@@ -0,0 +1,285 @@
+import { lstat, readdir, readFile, realpath, stat, unlink } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { isProductRepository } from "../lib/brain-path.js";
+import { BrainError } from "../lib/errors.js";
+import { atomicWriteFile, ensureDirectory } from "../lib/fs-safe.js";
+import { scanNotes } from "../lib/notes.js";
+import { assertPlainPath, listShippedSkillFiles } from "../lib/skills.js";
+const START = "<!-- ultimate-brain:start -->";
+const END = "<!-- ultimate-brain:end -->";
+const STACK = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** `brain link <repo-path>` (spec/cli.md §5.12). */
+export const linkCommand = {
+    name: "link",
+    usage: "brain link <repo-path> [--project <id>] [--area <id>] [--stack <name>]… [--repo-name <name>] [--json]",
+    summary: "Link a consuming repository to this brain and install its consult instruction.",
+    options: { project: "string", area: "string", stack: "list", "repo-name": "string" },
+    maxPositionals: 1,
+    needsBrain: true,
+    async run({ args, brain }) {
+        const [requested] = args.positionals;
+        if (requested === undefined)
+            throw new BrainError("USAGE", "brain link needs a repository path");
+        const root = await openRepo(requested);
+        if (root === brain.root || await isProductRepository(root)) {
+            throw new BrainError("OUTSIDE_ROOT", "Refusing to write a brain or product repository as a consuming repository");
+        }
+        const { notes } = await scanNotes(brain.root);
+        const existingMarker = await readMarker(root);
+        const marker = buildMarker(existingMarker, root, args.options, notes);
+        const project = marker.project === undefined ? undefined : noteOf(notes, marker.project, "project");
+        const area = marker.area === undefined ? undefined : noteOf(notes, marker.area, "area");
+        const block = instructionBlock(project, area);
+        const agents = await readOptional(root, "AGENTS.md");
+        const claude = await readOptional(root, "CLAUDE.md");
+        const agentText = replaceOrAppend(agents, block, "AGENTS.md");
+        const claudeText = claude === null
+            ? "@AGENTS.md\n"
+            : hasAgentImport(claude) ? claude : replaceOrAppend(claude, block, "CLAUDE.md");
+        const planned = [
+            { path: ".brain", before: existingMarker.raw, after: `${JSON.stringify(marker, null, 2)}\n` },
+            { path: "AGENTS.md", before: agents, after: agentText },
+            { path: "CLAUDE.md", before: claude, after: claudeText },
+            ...await planSkill(root),
+        ];
+        await writePlan(root, planned);
+        const action = (file) => file.before === null ? "created" : file.after === null ? "removed" : file.before === file.after ? "unchanged" : "updated";
+        return {
+            data: {
+                repo_abs: root,
+                marker: { path: ".brain", written: planned[0].before !== planned[0].after, value: marker },
+                files: planned.slice(1).map((file) => ({ path: file.path, action: action(file) })),
+            },
+            human: `Linked ${root} to the brain.\n`,
+        };
+    },
+};
+async function openRepo(requested) {
+    const path = resolve(requested);
+    try {
+        if (!(await stat(path)).isDirectory())
+            throw new BrainError("USAGE", `Repository path is not a directory: ${path}`);
+        return await realpath(path);
+    }
+    catch (error) {
+        if (error instanceof BrainError)
+            throw error;
+        throw new BrainError("USAGE", `Repository path does not exist or cannot be read: ${path}`);
+    }
+}
+async function readMarker(root) {
+    const raw = await readOptional(root, ".brain");
+    if (raw === null)
+        return { raw, value: {} };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new BrainError("INPUT_INVALID", `.brain is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isMarker(parsed))
+        throw new BrainError("INPUT_INVALID", ".brain must be an object with only repo, project, area and stacks");
+    return { raw, value: parsed };
+}
+function buildMarker(previous, root, options, notes) {
+    const marker = { ...previous.value };
+    marker.repo = options["repo-name"] ?? basename(root);
+    const requestedProject = options.project;
+    const requestedArea = options.area;
+    if (requestedProject !== undefined) {
+        const project = noteOf(notes, requestedProject, "project");
+        marker.project = project.id;
+        marker.area = requestedArea === undefined ? areaOf(project) : noteOf(notes, requestedArea, "area").id;
+    }
+    else if (requestedArea !== undefined) {
+        marker.area = noteOf(notes, requestedArea, "area").id;
+    }
+    if (options.stack !== undefined) {
+        const rawStacks = options.stack;
+        for (const stack of rawStacks) {
+            if (!STACK.test(stack))
+                throw new BrainError("USAGE", `--stack must be lowercase kebab-case: ${stack}`);
+        }
+        marker.stacks = [...new Set(rawStacks)].sort();
+    }
+    if (marker.project !== undefined)
+        noteOf(notes, marker.project, "project");
+    if (marker.area !== undefined)
+        noteOf(notes, marker.area, "area");
+    if (marker.stacks !== undefined)
+        marker.stacks = canonicalStacks(marker.stacks);
+    return orderedMarker(marker);
+}
+function areaOf(project) {
+    if (typeof project.attributes.area !== "string") {
+        throw new BrainError("UNKNOWN_ID", `Project ${project.id} has no area`);
+    }
+    return project.attributes.area;
+}
+function noteOf(notes, id, type) {
+    const note = notes.find((candidate) => candidate.id === id && candidate.type === type);
+    if (note === undefined)
+        throw new BrainError("UNKNOWN_ID", `No ${type} with id ${id}`);
+    return note;
+}
+function canonicalStacks(stacks) {
+    if (!stacks.every((stack) => typeof stack === "string" && STACK.test(stack))) {
+        throw new BrainError("INPUT_INVALID", ".brain stacks must be lowercase kebab-case strings");
+    }
+    return [...new Set(stacks)].sort();
+}
+function orderedMarker(marker) {
+    const ordered = {};
+    if (marker.repo !== undefined)
+        ordered.repo = marker.repo;
+    if (marker.project !== undefined)
+        ordered.project = marker.project;
+    if (marker.area !== undefined)
+        ordered.area = marker.area;
+    if (marker.stacks !== undefined)
+        ordered.stacks = marker.stacks;
+    return ordered;
+}
+function instructionBlock(project, area) {
+    const lines = [
+        START,
+        "## Ultimate Brain",
+        "",
+        "Managed by `brain link`; edits inside this block are overwritten.",
+        "",
+        `This repo is linked to the user's second brain${project === undefined && area === undefined ? "." : ":"}`,
+    ];
+    if (project !== undefined)
+        lines.push(`- Project: ${String(project.attributes.title)} (\`${project.id}\`)`);
+    if (area !== undefined)
+        lines.push(`- Area: ${String(area.attributes.title)} (\`${area.id}\`)`);
+    lines.push("", "The brain holds decisions, key facts, people and meeting history that this repo does not.", "", "Consult it before you:", "- make or revisit a decision about scope, architecture, vendors or the client;", "- answer why something was decided, who someone is, or a date, budget or owner;", "- rely on a fact about the client or project that this repo does not state.", "", "How: use the `brain-query` skill, or run `brain query --candidates \"<question>\" --json` and read the notes it returns. Cite the note paths. Say when a fact is `contested` or `superseded`.", "", "The brain is read-only from this repo. Never edit its files from here.", END);
+    return lines.join("\n");
+}
+function replaceOrAppend(existing, block, file) {
+    if (existing === null || existing === "")
+        return `${block}\n`;
+    const range = blockRange(existing);
+    if (range !== undefined)
+        return `${existing.slice(0, range.start)}${block}${existing.slice(range.end)}`;
+    if (existing.includes(START) || existing.includes(END)) {
+        throw new BrainError("INPUT_INVALID", `${file} has malformed Ultimate Brain markers`);
+    }
+    return `${existing}${existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n"}${block}\n`;
+}
+function blockRange(content) {
+    const start = markerPositions(content, START);
+    const end = markerPositions(content, END);
+    if (start.length === 0 && end.length === 0)
+        return undefined;
+    if (start.length !== 1 || end.length !== 1 || start[0] >= end[0]) {
+        throw new BrainError("INPUT_INVALID", "Ultimate Brain markers must appear exactly once and in order");
+    }
+    return { start: start[0], end: end[0] + END.length };
+}
+function markerPositions(content, marker) {
+    const expression = new RegExp(`(?:^|\\n)${escapeRegExp(marker)}(?=\\n|$)`, "g");
+    return [...content.matchAll(expression)].map((match) => match.index + (match[0].startsWith("\n") ? 1 : 0));
+}
+function hasAgentImport(content) {
+    return content.split(/\r?\n/).some((line) => line === "@AGENTS.md");
+}
+async function readOptional(root, path) {
+    try {
+        const target = `${root}/${path}`;
+        if ((await lstat(target)).isSymbolicLink())
+            throw new BrainError("OUTSIDE_ROOT", `Refusing to replace a symbolic link: ${target}`);
+        return await readFile(target, "utf8");
+    }
+    catch (error) {
+        if (error instanceof BrainError)
+            throw error;
+        if (isNodeError(error) && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+/** Product-owned `.agents/skills/brain-query/` (decision 0029): replace changed files, remove stale ones. */
+async function planSkill(root) {
+    const shipped = await listShippedSkillFiles("brain-query");
+    const planned = [];
+    const keep = new Set();
+    await assertPlainPath(root, ".agents/skills/brain-query", "folder");
+    for (const file of shipped) {
+        const path = `.agents/skills/${file.relative}`;
+        await assertPlainPath(root, path);
+        keep.add(path);
+        planned.push({ path, before: await readOptional(root, path), after: file.content.toString("utf8") });
+    }
+    const folder = ".agents/skills/brain-query";
+    for (const path of await listFiles(root, folder)) {
+        await assertPlainPath(root, path);
+        if (!keep.has(path))
+            planned.push({ path, before: await readOptional(root, path), after: null });
+    }
+    return planned.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+async function listFiles(root, folder) {
+    let entries;
+    try {
+        entries = await readdir(join(root, folder), { withFileTypes: true });
+    }
+    catch (error) {
+        if (isNodeError(error) && (error.code === "ENOENT" || error.code === "ENOTDIR"))
+            return [];
+        throw error;
+    }
+    const paths = [];
+    for (const entry of entries) {
+        const path = `${folder}/${entry.name}`;
+        if (entry.isDirectory())
+            paths.push(...await listFiles(root, path));
+        else
+            paths.push(path);
+    }
+    return paths;
+}
+async function writePlan(root, files) {
+    const changed = files.filter((file) => file.before !== file.after);
+    const done = [];
+    try {
+        for (const file of changed) {
+            if (file.after === null)
+                await unlink(`${root}/${file.path}`);
+            else {
+                await ensureDirectory(root, file.path.split("/").slice(0, -1).join("/") || ".");
+                await atomicWriteFile(root, file.path, file.after);
+            }
+            done.push(file);
+        }
+    }
+    catch (error) {
+        for (const file of done.reverse()) {
+            if (file.before === null)
+                await unlink(`${root}/${file.path}`).catch(() => undefined);
+            else
+                await atomicWriteFile(root, file.path, file.before).catch(() => undefined);
+        }
+        throw error;
+    }
+}
+function isMarker(value) {
+    if (!isRecord(value))
+        return false;
+    if (!Object.keys(value).every((key) => ["repo", "project", "area", "stacks"].includes(key)))
+        return false;
+    return (value.repo === undefined || typeof value.repo === "string")
+        && (value.project === undefined || typeof value.project === "string")
+        && (value.area === undefined || typeof value.area === "string")
+        && (value.stacks === undefined || Array.isArray(value.stacks));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/commands/lint.js

@@ -0,0 +1,47 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { posix } from "node:path";
+import { BrainError } from "../lib/errors.js";
+import { lintBrain } from "../lib/lint.js";
+import { scanNotes } from "../lib/notes.js";
+/** `brain lint [<path>…] [--strict]` (spec/cli.md §5.10). */
+export const lintCommand = {
+    name: "lint",
+    usage: "brain lint [<path>…] [--strict] [--json]",
+    summary: "Validate notes, links and brain.json against the schema. Exits 1 on errors (or warnings with --strict).",
+    options: { strict: "boolean" },
+    needsBrain: true,
+    async run({ args, brain }) {
+        const root = brain.root;
+        const { notes, problems } = await scanNotes(root);
+        let indexMarkdown;
+        try {
+            indexMarkdown = await readFile(join(root, "index.md"), "utf8");
+        }
+        catch {
+            indexMarkdown = null;
+        }
+        const all = lintBrain({ root, notes, problems, brainConfig: brain.config, indexMarkdown });
+        // Path filters: note files, brain-relative folders (prefix match), brain.json, index.md. brain.json is always checked.
+        const known = new Set([...notes.map((note) => note.path), ...problems.map((problem) => problem.path), "brain.json", "index.md"]);
+        const filters = args.positionals.map((path) => posix.normalize(path).replace(/^\.\//, "").replace(/\/$/, ""));
+        for (const filter of filters) {
+            if (!known.has(filter) && ![...known].some((path) => path.startsWith(`${filter}/`))) {
+                throw new BrainError("USAGE", `No note file or folder "${filter}" in the brain`);
+            }
+        }
+        const matches = (path) => path === "brain.json" || filters.some((filter) => path === filter || path.startsWith(`${filter}/`));
+        const issues = filters.length === 0 ? all : all.filter((issue) => matches(issue.path));
+        const errors = issues.filter((issue) => issue.severity === "error").length;
+        const warnings = issues.length - errors;
+        const failed = errors > 0 || (args.options.strict === true && warnings > 0);
+        const human = issues.length === 0
+            ? "No issues.\n"
+            : `${issues.map((issue) => `${issue.path}:${issue.line} ${issue.severity} ${issue.rule}: ${issue.message}`).join("\n")}\n${errors} errors, ${warnings} warnings\n`;
+        return {
+            data: { errors, warnings, files: notes.length + problems.length, issues },
+            exitCode: failed ? 1 : 0,
+            human,
+        };
+    },
+};

package/dist/commands/log.js

@@ -0,0 +1,48 @@
+import { BrainError } from "../lib/errors.js";
+import { appendLog, formatLogLine } from "../lib/log.js";
+import { scanNotes } from "../lib/notes.js";
+const OP = /^[a-z][a-z0-9-]*$/;
+const KEY = /^[a-z][a-z0-9_]*$/;
+/** `brain log <op> [<id>] [--title <title>] [<key>=<value>…]` (spec/cli.md §5.11). */
+export const logCommand = {
+    name: "log",
+    usage: "brain log <op> [<id>|-] [--title <title>] [<key>=<value>…] [--json]",
+    summary: "Append one operation line to log/<YYYY-MM>.md.",
+    options: { title: "string" },
+    needsBrain: true,
+    async run({ args, brain, now }) {
+        const [op, ...rest] = args.positionals;
+        if (op === undefined || !OP.test(op)) {
+            throw new BrainError("USAGE", "brain log needs an <op> matching [a-z][a-z0-9-]*");
+        }
+        let id = "-";
+        const pairs = [];
+        for (const [index, value] of rest.entries()) {
+            const equals = value.indexOf("=");
+            if (equals !== -1) {
+                const key = value.slice(0, equals);
+                if (!KEY.test(key))
+                    throw new BrainError("USAGE", `Invalid key "${key}": keys match [a-z][a-z0-9_]*`);
+                pairs.push([key, value.slice(equals + 1)]);
+            }
+            else if (index === 0) {
+                id = value;
+            }
+            else {
+                throw new BrainError("USAGE", `Expected <key>=<value>, got "${value}"`);
+            }
+        }
+        let title = args.options.title;
+        if (id !== "-") {
+            const { notes } = await scanNotes(brain.root);
+            const note = notes.find((candidate) => candidate.id === id);
+            if (note === undefined)
+                throw new BrainError("UNKNOWN_ID", `No note with id ${id}`);
+            title ??= typeof note.attributes.title === "string" ? note.attributes.title : "";
+        }
+        const entry = { op, id, title: title ?? "", pairs };
+        const path = await appendLog(brain.root, now, [entry]);
+        const line = formatLogLine(now, entry);
+        return { data: { path, line }, human: `${line}\n` };
+    },
+};