ultimate-brain 0.0.0-stage → 0.2.0

package/dist/lib/time.js

@@ -0,0 +1,21 @@
+import { BrainError } from "./errors.js";
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+/** The command clock: `--now` when given (ISO 8601 UTC), else the system clock. */
+export function resolveNow(now) {
+    if (now === undefined)
+        return new Date();
+    const parsed = new Date(now);
+    // Reject impossible dates such as 2026-02-30, which Date would roll over into March.
+    if (!TIMESTAMP.test(now) || Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 19) !== now.slice(0, 19)) {
+        throw new BrainError("USAGE", `--now must be an ISO 8601 UTC timestamp like 2026-12-03T10:22:00Z, got "${now}"`);
+    }
+    return parsed;
+}
+/** `2026-12-03T10:22:00Z` (seconds precision, as the schema's timestamps). */
+export function formatTimestamp(date) {
+    return date.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/** `2026-12-03` in UTC. */
+export function formatDate(date) {
+    return date.toISOString().slice(0, 10);
+}

package/dist/lib/views.js

@@ -0,0 +1,139 @@
+import { posix } from "node:path";
+import { compareCodePoints } from "./notes.js";
+const CURRENT_ASSESSMENTS = new Set(["accepted", "provisional", "contested"]);
+/** Render one project view from canonical notes only (spec/schema.md §16). */
+export function deriveView(project, kind, notes) {
+    const canonical = notes.filter((note) => note.type !== "view");
+    const byId = new Map(canonical.map((note) => [note.id, note]));
+    const generated = new Set([project.id]);
+    const link = (note) => noteLink(projectViewPath(project, kind), note);
+    const title = (note) => text(note.attributes.title);
+    const add = (note) => {
+        generated.add(note.id);
+        return link(note);
+    };
+    const sections = kind === "brief"
+        ? briefSections(project, canonical, byId, title, add)
+        : decisionLogSections(project, canonical, byId, title, add, link);
+    const generatedBlock = ["<!-- @generated:start -->", ...sections.flatMap((section, index) => index === 0 ? section : ["", ...section]), "<!-- @generated:end -->"].join("\n");
+    return { kind, generatedBlock, generatedFrom: [...generated].sort(compareCodePoints) };
+}
+/** The standard view filename beside a project's `project.md`. */
+export function projectViewPath(project, kind) {
+    return `${posix.dirname(project.path)}/${kind === "brief" ? "brief.md" : "decision-log.md"}`;
+}
+/** Exactly one standalone start/end marker, in order, is required before replacement. */
+export function generatedBlockRange(body) {
+    const start = markerPositions(body, "<!-- @generated:start -->");
+    const end = markerPositions(body, "<!-- @generated:end -->");
+    if (start.length !== 1 || end.length !== 1 || start[0] >= end[0])
+        return undefined;
+    return { start: start[0], end: end[0] + "<!-- @generated:end -->".length };
+}
+function briefSections(project, notes, byId, title, add) {
+    const status = ["## Status"];
+    const notionFields = record(project.attributes.notion_fields);
+    const statusValue = scalar(notionFields.status);
+    const priority = scalar(notionFields.priority);
+    const asOf = scalar(notionFields.as_of);
+    if (statusValue !== undefined || priority !== undefined) {
+        const parts = [statusValue === undefined ? undefined : `Status: ${statusValue}`, priority === undefined ? undefined : `Priority: ${priority}`]
+            .filter((value) => value !== undefined);
+        const suffix = asOf === undefined ? "" : ` (as of ${asOf.slice(0, 10)})`;
+        status.push(`- ${parts.join(" · ")}${suffix} ([project](project.md))`);
+    }
+    for (const [key, value] of Object.entries(record(project.attributes.facts)).sort(([left], [right]) => compareCodePoints(left, right))) {
+        const person = typeof value === "string" ? byId.get(value) : undefined;
+        const rendered = person?.type === "person" ? add(person) : String(value);
+        status.push(`- ${formatFactKey(key)}: ${rendered} ([project](project.md))`);
+    }
+    if (status.length === 1)
+        status.push("- None");
+    const goal = typeof project.attributes.goal === "string" ? byId.get(project.attributes.goal) : undefined;
+    const goalSection = ["## Goal", goal?.type === "goal" ? `- ${add(goal)}` : "- None"];
+    const people = list(project.attributes.people)
+        .map((id) => typeof id === "string" ? byId.get(id) : undefined)
+        .filter((note) => note?.type === "person")
+        .sort((left, right) => compareCodePoints(title(left), title(right)) || compareCodePoints(left.id, right.id));
+    const peopleSection = ["## People", ...(people.length === 0 ? ["- None"] : people.map((person) => {
+            const role = scalar(record(person.attributes.facts).role);
+            return `- ${add(person)}${role === undefined ? "" : ` — ${role}`}`;
+        }))];
+    const decisions = notes
+        .filter((note) => note.type === "decision" && belongsToProject(note, project) && CURRENT_ASSESSMENTS.has(String(note.attributes.assessment)))
+        .sort(sortDescendingBy("date"))
+        .slice(0, 5);
+    const decisionsSection = ["## Recent decisions", ...(decisions.length === 0 ? ["- None"] : decisions.map((decision) => `- ${text(decision.attributes.date)} — ${add(decision)} (${text(decision.attributes.assessment)})`))];
+    const questions = notes
+        .filter((note) => note.type === "question" && belongsToProject(note, project))
+        .filter((note) => {
+        const status = record(note.attributes.notion_fields).status;
+        return status === undefined || status === "Open";
+    })
+        .sort(sortDescendingBy("created"));
+    const questionsSection = ["## Open questions", ...(questions.length === 0 ? ["- None"] : questions.map((question) => `- ${add(question)} (${text(question.attributes.kind)})`))];
+    const meetings = notes
+        .filter((note) => note.type === "meeting" && belongsToProject(note, project))
+        .sort(sortDescendingBy("date"))
+        .slice(0, 5);
+    const meetingsSection = ["## Recent meetings", ...(meetings.length === 0 ? ["- None"] : meetings.map((meeting) => `- ${text(meeting.attributes.date)} — ${add(meeting)}`))];
+    return [status, goalSection, peopleSection, decisionsSection, questionsSection, meetingsSection];
+}
+function decisionLogSections(project, notes, byId, _title, add, link) {
+    const decisions = notes.filter((note) => note.type === "decision" && belongsToProject(note, project));
+    const current = decisions.filter((note) => CURRENT_ASSESSMENTS.has(String(note.attributes.assessment))).sort(sortDescendingBy("date"));
+    const superseded = decisions.filter((note) => note.attributes.assessment === "superseded").sort(sortDescendingBy("valid_until"));
+    const currentSection = ["## Current", ...(current.length === 0 ? ["- None"] : current.map((decision) => {
+            const older = relationTarget(decision, "supersedes", byId);
+            return `- ${text(decision.attributes.date)} — ${add(decision)} — ${text(decision.attributes.assessment)}${older === undefined ? "" : ` — supersedes ${link(older)}`}`;
+        }))];
+    const supersededSection = ["## Superseded", ...(superseded.length === 0 ? ["- None"] : superseded.map((decision) => {
+            const replacement = relationTarget(decision, "superseded_by", byId);
+            const from = scalar(decision.attributes.valid_from) ?? text(decision.attributes.date);
+            const until = text(decision.attributes.valid_until);
+            return `- ${from} → ${until} — ${add(decision)} — superseded by ${replacement === undefined ? "(unknown)" : link(replacement)}`;
+        }))];
+    return [currentSection, supersededSection];
+}
+function relationTarget(note, type, byId) {
+    for (const relation of list(note.attributes.relations)) {
+        const recordValue = record(relation);
+        if (recordValue.type === type && typeof recordValue.target === "string")
+            return byId.get(recordValue.target);
+    }
+    return undefined;
+}
+function belongsToProject(note, project) {
+    return list(note.attributes.projects).includes(project.id);
+}
+function sortDescendingBy(field) {
+    return (left, right) => compareCodePoints(text(right.attributes[field]), text(left.attributes[field])) || compareCodePoints(left.id, right.id);
+}
+function noteLink(fromPath, note) {
+    const title = text(note.attributes.title).replaceAll("\\", "\\\\").replaceAll("[", "\\[").replaceAll("]", "\\]");
+    return `[${title}](${posix.relative(posix.dirname(fromPath), note.path)})`;
+}
+function markerPositions(body, marker) {
+    const expression = new RegExp(`(?:^|\\n)${escapeRegExp(marker)}(?=\\n|$)`, "g");
+    return [...body.matchAll(expression)].map((match) => match.index + (match[0].startsWith("\n") ? 1 : 0));
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function formatFactKey(key) {
+    return key.replaceAll("_", " ").replace(/^./, (first) => first.toUpperCase());
+}
+function text(value) {
+    return value === undefined || value === null ? "" : String(value);
+}
+function scalar(value) {
+    return typeof value === "string" || typeof value === "number" ? String(value) : undefined;
+}
+function list(value) {
+    return Array.isArray(value) ? value : [];
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}

package/dist/lib/warnings.js

@@ -0,0 +1,9 @@
+/** Convert staged lint issues to the warning envelope used by writing commands. */
+export function lintWarnings(issues) {
+    return issues.map((issue) => ({
+        code: issue.rule.toUpperCase().replaceAll("-", "_"),
+        message: `${issue.path}:${issue.line} ${issue.message}`,
+        path: issue.path,
+        ...(issue.id === null ? {} : { id: issue.id }),
+    }));
+}

package/dist/lib/workspace.js

@@ -0,0 +1,183 @@
+import { existsSync } from "node:fs";
+import { rmdir, unlink } from "node:fs/promises";
+import { join, posix } from "node:path";
+import { BrainError } from "./errors.js";
+import { parseFrontmatter, serializeFrontmatter } from "./frontmatter.js";
+import { atomicCreateFile, atomicWriteFile, ensureDirectory } from "./fs-safe.js";
+import { lintBrain } from "./lint.js";
+import { appendLog } from "./log.js";
+import { compareCodePoints, parseNote, scanNotes } from "./notes.js";
+/**
+ * The brain as one command sees it: notes read from disk plus the writes the command has
+ * staged. Writes are validated in memory (spec/cli.md §3.6.1) and land together on `commit`,
+ * which restores every file it had touched if a write fails (§3.6.3).
+ */
+export class Workspace {
+    root;
+    config;
+    problems;
+    notesByPath;
+    staged = new Map();
+    baseline;
+    constructor(brain, notes, problems) {
+        this.root = brain.root;
+        this.config = brain.config;
+        this.problems = problems;
+        this.notesByPath = new Map(notes.map((note) => [note.path, note]));
+    }
+    static async open(brain) {
+        const { notes, problems } = await scanNotes(brain.root);
+        return new Workspace(brain, notes, problems);
+    }
+    /** Every note, staged writes included, sorted by path. */
+    get notes() {
+        return [...this.notesByPath.values()].sort((a, b) => compareCodePoints(a.path, b.path));
+    }
+    /** The note with this id (the first by path if duplicated). */
+    get(id) {
+        return this.notes.find((note) => note.id === id);
+    }
+    ids() {
+        return new Set(this.notes.map((note) => note.id));
+    }
+    /** Whether a file or folder exists at this brain-relative path, on disk or staged. */
+    exists(path) {
+        if (this.staged.has(path))
+            return true;
+        for (const staged of this.staged.keys())
+            if (staged.startsWith(`${path}/`))
+                return true;
+        return existsSync(join(this.root, path));
+    }
+    /** A parsed, editable copy of a note; pass it to `save` after changing it. */
+    edit(note) {
+        return parseFrontmatter(note.raw);
+    }
+    save(path, document) {
+        this.write(path, serializeFrontmatter(document));
+    }
+    /** Stage a file. Its content must parse as a note. */
+    write(path, content) {
+        const parsed = parseNote(path, content);
+        if ("code" in parsed)
+            throw new Error(`Refusing to stage ${path}: ${parsed.message}`);
+        const previous = this.staged.get(path);
+        const original = previous !== undefined ? previous.original : this.notesByPath.get(path)?.raw ?? null;
+        if (original === content)
+            this.staged.delete(path);
+        else
+            this.staged.set(path, { content, original });
+        this.notesByPath.set(path, parsed);
+    }
+    checkpoint() {
+        return { staged: new Map(this.staged), notes: new Map(this.notesByPath) };
+    }
+    restore(checkpoint) {
+        this.staged = new Map(checkpoint.staged);
+        this.notesByPath = new Map(checkpoint.notes);
+    }
+    /** Paths whose content changed since the checkpoint, sorted. */
+    changedSince(checkpoint) {
+        return [...this.notesByPath.entries()]
+            .filter(([path, note]) => checkpoint.notes.get(path)?.raw !== note.raw)
+            .map(([path]) => path)
+            .sort(compareCodePoints);
+    }
+    /** Paths with staged writes, sorted. */
+    get changedPaths() {
+        return [...this.staged.keys()].sort(compareCodePoints);
+    }
+    isNew(path) {
+        return this.staged.get(path)?.original === null;
+    }
+    /**
+     * Lint errors that the staged writes introduce, anywhere in the brain (or only in `paths`):
+     * errors that were there before the command are not counted, so an old problem never blocks
+     * an unrelated change.
+     */
+    newErrors(paths) {
+        this.baseline ??= new Set(this.issues(this.initialNotes(), new Set()).filter((issue) => issue.severity === "error").map(issueKey));
+        const wanted = paths === undefined ? undefined : new Set(paths);
+        return this.issues(this.notes, new Set(this.staged.keys()))
+            .filter((issue) => issue.severity === "error")
+            .filter((issue) => (wanted === undefined || wanted.has(issue.path)) && !this.baseline.has(issueKey(issue)));
+    }
+    /** Lint warnings for staged files, reported by commands that write those files. */
+    warnings(paths = this.staged.keys()) {
+        const wanted = new Set(paths);
+        return this.issues(this.notes, new Set(this.staged.keys()))
+            .filter((issue) => issue.severity === "warning" && wanted.has(issue.path));
+    }
+    /**
+     * Write every staged file, then append `log` lines (spec/cli.md §3.9). If anything fails,
+     * restore the files and remove the folders this commit created. Refusal BrainErrors such as
+     * WRITE_CONFLICT pass through after rollback; unexpected failures become INTERNAL.
+     */
+    async commit(log = [], now = new Date()) {
+        const done = [];
+        const folders = [];
+        try {
+            for (const path of this.changedPaths) {
+                const staged = this.staged.get(path);
+                folders.push(...missingFolders(this.root, posix.dirname(path)));
+                await ensureDirectory(this.root, posix.dirname(path));
+                if (staged.original === null)
+                    await atomicCreateFile(this.root, path, staged.content);
+                else
+                    await atomicWriteFile(this.root, path, staged.content);
+                done.push([path, staged]);
+            }
+            if (log.length > 0)
+                await appendLog(this.root, now, log);
+        }
+        catch (error) {
+            for (const [path, staged] of done.reverse()) {
+                if (staged.original === null)
+                    await unlink(join(this.root, path)).catch(() => undefined);
+                else
+                    await atomicWriteFile(this.root, path, staged.original).catch(() => undefined);
+            }
+            for (const folder of folders.reverse())
+                await rmdir(join(this.root, folder)).catch(() => undefined);
+            if (error instanceof BrainError && error.code !== "INTERNAL")
+                throw error;
+            throw new BrainError("INTERNAL", `Write failed; restored the files already written: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const created = done.filter(([, staged]) => staged.original === null).map(([path]) => path);
+        const changed = done.filter(([, staged]) => staged.original !== null).map(([path]) => path);
+        this.staged.clear();
+        return { created, changed };
+    }
+    initialNotes() {
+        const notes = [];
+        for (const note of this.notesByPath.values()) {
+            const staged = this.staged.get(note.path);
+            if (staged === undefined)
+                notes.push(note);
+            else if (staged.original !== null)
+                notes.push(parseNote(note.path, staged.original));
+        }
+        return notes.sort((a, b) => compareCodePoints(a.path, b.path));
+    }
+    issues(notes, pendingPaths) {
+        return lintBrain({
+            root: this.root,
+            notes,
+            problems: this.problems,
+            brainConfig: this.config,
+            indexMarkdown: undefined,
+            pendingPaths,
+        });
+    }
+}
+/** Folders on the way to `folder` that do not exist yet, outermost first. */
+function missingFolders(root, folder) {
+    const missing = [];
+    for (let current = folder; current !== "." && current !== "" && !existsSync(join(root, current)); current = posix.dirname(current)) {
+        missing.unshift(current);
+    }
+    return missing;
+}
+function issueKey(issue) {
+    return `${issue.path}\u0000${issue.rule}\u0000${issue.message}`;
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "ultimate-brain",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "CLI for an AI-assisted Markdown and Git second brain",
+  "license": "MIT",
+  "keywords": [
+    "second-brain",
+    "knowledge-management",
+    "markdown",
+    "notion",
+    "claude-code",
+    "codex",
+    "cli"
+  ],
+  "type": "module",
+  "bin": {
+    "ultimate-brain": "bin/brain.js",
+    "brain": "bin/brain.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "spec/schemas",
+    "templates/brain",
+    ".agents/skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc --project tsconfig.build.json",
+    "prepack": "npm run build",
+    "test:package": "node scripts/test-package.mjs",
+    "test": "node --experimental-strip-types --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=22.6"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  }
+}

package/spec/schemas/brain.schema.json

@@ -0,0 +1,200 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ultimate-brain.dev/schemas/v1/brain.schema.json",
+  "title": "brain.json (v1)",
+  "description": "Per-brain configuration. See spec/schema.md §12 and decisions 0014, 0018.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "owner",
+    "budgets",
+    "notion"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "owner": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "budgets": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "ingest_max_notes": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 20,
+          "default": 8
+        }
+      }
+    },
+    "notion": {
+      "type": "object",
+      "required": [
+        "databases",
+        "tasks"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "databases": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "areas": {
+              "$ref": "#/$defs/dbId"
+            },
+            "goals": {
+              "$ref": "#/$defs/dbId"
+            },
+            "key_results": {
+              "$ref": "#/$defs/dbId"
+            },
+            "projects": {
+              "$ref": "#/$defs/dbId"
+            },
+            "meetings": {
+              "$ref": "#/$defs/dbId"
+            },
+            "people": {
+              "$ref": "#/$defs/dbId"
+            },
+            "orgs": {
+              "$ref": "#/$defs/dbId"
+            },
+            "decisions": {
+              "$ref": "#/$defs/dbId"
+            },
+            "questions": {
+              "$ref": "#/$defs/dbId"
+            },
+            "review": {
+              "$ref": "#/$defs/dbId"
+            },
+            "capture_inbox": {
+              "$ref": "#/$defs/dbId"
+            }
+          }
+        },
+        "tasks": {
+          "type": "object",
+          "required": [
+            "database",
+            "properties",
+            "new_task_status"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "database": {
+              "$ref": "#/$defs/dbId"
+            },
+            "properties": {
+              "type": "object",
+              "required": [
+                "title"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "title": {
+                  "type": "string"
+                },
+                "status": {
+                  "type": "string"
+                },
+                "due": {
+                  "type": "string"
+                },
+                "project": {
+                  "type": "string"
+                },
+                "area": {
+                  "type": "string"
+                },
+                "owner": {
+                  "type": "string"
+                },
+                "meeting": {
+                  "type": "string"
+                },
+                "meeting_url": {
+                  "type": "string"
+                },
+                "brain_id": {
+                  "type": "string"
+                }
+              }
+            },
+            "new_task_status": {
+              "type": "string"
+            }
+          },
+          "allOf": [
+            {
+              "if": {
+                "properties": {
+                  "database": {
+                    "minLength": 1
+                  }
+                },
+                "required": [
+                  "database"
+                ]
+              },
+              "then": {
+                "properties": {
+                  "properties": {
+                    "properties": {
+                      "title": {
+                        "minLength": 1
+                      }
+                    },
+                    "anyOf": [
+                      {
+                        "properties": {
+                          "meeting": {
+                            "minLength": 1
+                          }
+                        },
+                        "required": [
+                          "meeting"
+                        ]
+                      },
+                      {
+                        "properties": {
+                          "meeting_url": {
+                            "minLength": 1
+                          }
+                        },
+                        "required": [
+                          "meeting_url"
+                        ]
+                      }
+                    ]
+                  }
+                }
+              }
+            }
+          ]
+        }
+      }
+    }
+  },
+  "$defs": {
+    "dbId": {
+      "description": "Notion database id; empty string until `brain connect-notion` fills it.",
+      "type": "string",
+      "pattern": "^$|^[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}$"
+    }
+  }
+}