ultimate-brain 0.0.0-stage → 0.2.0

package/dist/lib/brain.js

@@ -0,0 +1,36 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveBrainDirectory } from "./brain-path.js";
+import { BrainError } from "./errors.js";
+/**
+ * Resolve the brain (spec/cli.md §4) and read its `brain.json`.
+ * Full JSON Schema validation of `brain.json` arrives with the validator in CX-05;
+ * until then only presence, JSON syntax and `schema_version` are checked.
+ */
+export async function openBrain(options = {}) {
+    const root = await resolveBrainDirectory(options);
+    const configPath = join(root, "brain.json");
+    let raw;
+    try {
+        raw = await readFile(configPath, "utf8");
+    }
+    catch {
+        throw new BrainError("BRAIN_NOT_FOUND", `Not a brain: ${root} has no brain.json`);
+    }
+    let config;
+    try {
+        config = JSON.parse(raw);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new BrainError("BRAIN_CONFIG_INVALID", `brain.json is not valid JSON: ${detail}`);
+    }
+    if (typeof config !== "object" || config === null || Array.isArray(config)) {
+        throw new BrainError("BRAIN_CONFIG_INVALID", "brain.json must be a JSON object");
+    }
+    const version = config.schema_version;
+    if (version !== 1) {
+        throw new BrainError("SCHEMA_VERSION_UNSUPPORTED", `brain.json schema_version is ${JSON.stringify(version)}; this CLI supports 1`);
+    }
+    return { root, config: config };
+}

package/dist/lib/command.js

@@ -0,0 +1,61 @@
+import { parseArgs } from "./args.js";
+import { openBrain } from "./brain.js";
+import { BrainError, exitCodeFor } from "./errors.js";
+import { resolveNow } from "./time.js";
+/** Run one command and print its result or error (spec/cli.md §3.3). Returns the exit code. */
+export async function runCommand(command, argv, io, environment = {}) {
+    const separator = argv.indexOf("--");
+    const json = (separator === -1 ? argv : argv.slice(0, separator)).includes("--json");
+    let brainRoot = null;
+    try {
+        const args = parseArgs(argv, command.options);
+        if (command.maxPositionals !== undefined && args.positionals.length > command.maxPositionals) {
+            throw new BrainError("USAGE", `Unexpected argument: ${args.positionals[command.maxPositionals]}`);
+        }
+        if (args.options.help === true) {
+            io.stdout.write(`Usage: ${command.usage}\n\n${command.summary}\n`);
+            return 0;
+        }
+        const now = resolveNow(args.options.now);
+        let brain = null;
+        if (command.needsBrain) {
+            brain = await openBrain({
+                brainFlag: args.options.brain,
+                env: environment.env,
+                homeDirectory: environment.homeDirectory,
+            });
+            brainRoot = brain.root;
+        }
+        const result = await command.run({ args, brain, now, environment });
+        const warnings = result.warnings ?? [];
+        if (json) {
+            writeJson(io, { ok: true, command: command.name, brain: result.resolvedBrain ?? brainRoot, data: result.data, warnings });
+        }
+        else {
+            io.stdout.write(result.human ?? `${JSON.stringify(result.data, null, 2)}\n`);
+            for (const warning of warnings)
+                io.stderr.write(`warning: ${warning.message}\n`);
+        }
+        return result.exitCode ?? 0;
+    }
+    catch (error) {
+        const known = error instanceof BrainError;
+        const code = known ? error.code : "INTERNAL";
+        const message = error instanceof Error ? error.message : String(error);
+        if (json) {
+            const body = { code, message };
+            if (known && error.details !== undefined)
+                body.details = error.details;
+            writeJson(io, { ok: false, command: command.name, brain: brainRoot, error: body, warnings: [] });
+        }
+        else {
+            io.stderr.write(`error: ${message}\n`);
+        }
+        if (!known && error instanceof Error && error.stack !== undefined)
+            io.stderr.write(`${error.stack}\n`);
+        return exitCodeFor(code);
+    }
+}
+function writeJson(io, value) {
+    io.stdout.write(`${JSON.stringify(value)}\n`);
+}

package/dist/lib/errors.js

@@ -0,0 +1,33 @@
+/** Error codes and exit codes from spec/cli.md §3.4–3.5. */
+export const EXIT_CODES = {
+    USAGE: 2,
+    BRAIN_NOT_CONFIGURED: 3,
+    BRAIN_NOT_FOUND: 3,
+    BRAIN_IS_PRODUCT_REPO: 3,
+    BRAIN_CONFIG_INVALID: 3,
+    SCHEMA_VERSION_UNSUPPORTED: 3,
+    INPUT_UNREADABLE: 4,
+    INPUT_INVALID: 4,
+    UNKNOWN_ID: 4,
+    ID_IN_USE: 4,
+    BEFORE_MISMATCH: 4,
+    TARGET_NOT_EMPTY: 5,
+    ALREADY_A_BRAIN: 5,
+    OUTSIDE_ROOT: 5,
+    WRITE_CONFLICT: 5,
+    INTERNAL: 10,
+};
+/** An expected failure with a contract error code; anything else is INTERNAL. */
+export class BrainError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "BrainError";
+        this.code = code;
+        this.details = details;
+    }
+}
+export function exitCodeFor(code) {
+    return EXIT_CODES[code];
+}

package/dist/lib/frontmatter.js

@@ -0,0 +1,171 @@
+import { isDeepStrictEqual } from "node:util";
+import { Document, isMap, isScalar, isSeq, parseDocument, visit } from "yaml";
+const parsedDocuments = new WeakMap();
+/** Serialization options of spec/cli.md §3.6.5. */
+const TO_STRING = { lineWidth: 0, flowCollectionPadding: false };
+const KNOWLEDGE_HEAD = ["id", "type", "title", "summary", "lifecycle"];
+const KNOWLEDGE_TAIL = [
+    "aliases", "tags", "area", "projects", "sources", "relations", "facts", "timeline",
+    "created", "updated", "notion", "last_synced", "notion_fields", "notion_published",
+];
+/** Each type's own fields, in the order of its table in spec/schema.md §4. */
+const TYPE_FIELDS = {
+    goal: ["why", "area"],
+    project: ["area", "goal", "client", "people"],
+    person: ["org"],
+    meeting: ["date", "attendees", "source", "decisions", "questions", "tasks"],
+    decision: ["date", "assessment", "decided_in", "deciders", "valid_from", "valid_until"],
+    question: ["kind", "raised_in", "answer"],
+    source: ["source_key", "kind", "file_name", "converter", "content_hash", "captured", "origin_edited"],
+    view: ["view_kind", "project", "generated_from", "generated_at"],
+    memory: ["scope", "areas", "projects", "stacks", "confidence", "origin"],
+};
+/** Proposal key order: the spec/schema.md §11 example, then its table. */
+const PROPOSAL_ORDER = [
+    "id", "type", "title", "created", "updated", "kind", "target", "field", "before", "after", "from",
+    "content", "note", "supersedes", "merge_into", "why", "source", "status", "decision", "closed_reason",
+    "notion", "notion_published",
+];
+/** Canonical rank of each key for a type (spec/cli.md §3.6.5); a key listed twice keeps its first position. */
+function keyOrder(type) {
+    const keys = type === "proposal"
+        ? PROPOSAL_ORDER
+        : [...KNOWLEDGE_HEAD, ...(TYPE_FIELDS[String(type)] ?? []), ...KNOWLEDGE_TAIL];
+    const ranks = new Map();
+    for (const key of keys)
+        if (!ranks.has(key))
+            ranks.set(key, ranks.size);
+    return ranks;
+}
+/** Parse a Markdown file with a YAML 1.2 core-schema frontmatter mapping. */
+export function parseFrontmatter(source) {
+    const opening = /^---(?:\r\n|\n)/.exec(source);
+    if (opening === null) {
+        throw new Error("Markdown file must start with a YAML frontmatter delimiter");
+    }
+    const afterOpening = source.slice(opening[0].length);
+    const closing = /^---(?:\r\n|\n|$)/m.exec(afterOpening);
+    if (closing === null) {
+        throw new Error("YAML frontmatter is missing its closing delimiter");
+    }
+    const yamlSource = afterOpening.slice(0, closing.index);
+    const yamlDocument = parseDocument(yamlSource, {
+        schema: "core",
+        prettyErrors: true,
+        uniqueKeys: true,
+    });
+    if (yamlDocument.errors.length > 0) {
+        throw new Error(`Invalid YAML frontmatter: ${yamlDocument.errors[0].message}`);
+    }
+    if (yamlDocument.contents !== null && !isMap(yamlDocument.contents)) {
+        throw new Error("YAML frontmatter must contain a top-level mapping");
+    }
+    const parsed = yamlDocument.contents === null ? {} : yamlDocument.toJS();
+    if (!isRecord(parsed)) {
+        throw new Error("YAML frontmatter must contain a top-level mapping");
+    }
+    const body = afterOpening.slice(closing.index + closing[0].length);
+    const document = {
+        attributes: parsed,
+        body,
+        originalSource: source,
+        originalAttributes: structuredClone(parsed),
+        originalBody: body,
+    };
+    parsedDocuments.set(document, yamlDocument);
+    return document;
+}
+/**
+ * Serialize an edited file, preserving the original bytes when unchanged. Existing keys keep
+ * their place and unknown keys are kept; a new key goes where the canonical order puts it among
+ * the keys present (spec/cli.md §3.6.5).
+ */
+export function serializeFrontmatter(document) {
+    if (document.originalSource !== undefined &&
+        document.originalAttributes !== undefined &&
+        document.originalBody !== undefined &&
+        isDeepStrictEqual(document.attributes, document.originalAttributes) &&
+        document.body === document.originalBody) {
+        return document.originalSource;
+    }
+    const yaml = serializeAttributes(document);
+    return `---\n${yaml}---\n${document.body}`;
+}
+/**
+ * Serialize a new file (spec/cli.md §3.6.5): keys in canonical order (unknown keys last, in
+ * input order), one blank line before the body (none for a source), nothing after the closing
+ * `---` when the body is empty.
+ */
+export function serializeNewFile(attributes, body) {
+    const ranks = keyOrder(attributes.type);
+    const rank = (key) => ranks.get(key) ?? Number.MAX_SAFE_INTEGER;
+    const ordered = Object.fromEntries(Object.entries(attributes).sort(([a], [b]) => rank(a) - rank(b)));
+    const yamlDocument = new Document(ordered, { schema: "core" });
+    applyCollectionStyle(yamlDocument.contents);
+    const yaml = yamlDocument.toString(TO_STRING);
+    if (body === "")
+        return `---\n${yaml}---\n`;
+    return `---\n${yaml}---\n${attributes.type === "source" ? "" : "\n"}${body}`;
+}
+function serializeAttributes(document) {
+    if (Object.keys(document.attributes).length === 0)
+        return "";
+    const original = parsedDocuments.get(document);
+    const yamlDocument = original?.clone() ?? new Document({}, { schema: "core" });
+    if (yamlDocument.contents === null)
+        yamlDocument.contents = yamlDocument.createNode({});
+    const map = yamlDocument.contents;
+    if (!isMap(map)) {
+        throw new Error("YAML frontmatter must contain a top-level mapping");
+    }
+    const current = yamlDocument.toJS();
+    for (const key of Object.keys(current)) {
+        if (!Object.hasOwn(document.attributes, key))
+            yamlDocument.delete(key);
+    }
+    const ranks = keyOrder(document.attributes.type);
+    for (const [key, value] of Object.entries(document.attributes)) {
+        if (Object.hasOwn(current, key) && isDeepStrictEqual(current[key], value))
+            continue;
+        const node = yamlDocument.createNode(value);
+        applyCollectionStyle(node);
+        if (Object.hasOwn(current, key)) {
+            yamlDocument.set(key, node);
+            continue;
+        }
+        // Insert before the first present key that the canonical order puts after this one.
+        const pair = yamlDocument.createPair(key, node);
+        const rank = ranks.get(key);
+        const index = rank === undefined
+            ? -1
+            : map.items.findIndex((item) => {
+                const other = ranks.get(String(isScalar(item.key) ? item.key.value : item.key));
+                return other !== undefined && other > rank;
+            });
+        if (index === -1)
+            map.items.push(pair);
+        else
+            map.items.splice(index, 0, pair);
+    }
+    return yamlDocument.toString(TO_STRING);
+}
+/** Lists of scalars in flow style (`[a, b]`, `[]`); mappings and lists of mappings in block style. */
+function applyCollectionStyle(node) {
+    if (isSeq(node))
+        node.flow = node.items.every((item) => isScalar(item));
+    if (isMap(node))
+        node.flow = false;
+    if (!isSeq(node) && !isMap(node))
+        return;
+    visit(node, {
+        Map(_, map) {
+            map.flow = false;
+        },
+        Seq(_, seq) {
+            seq.flow = seq.items.every((item) => isScalar(item));
+        },
+    });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/lib/fs-safe.js

@@ -0,0 +1,140 @@
+import { link, lstat, mkdir, open, realpath, rename, unlink } from "node:fs/promises";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { randomBytes } from "node:crypto";
+import { BrainError } from "./errors.js";
+/**
+ * Resolve a write target inside a root: the target and its real parent must be contained,
+ * the parent must exist, and an existing target must not be a symbolic link.
+ * Every refusal is an OUTSIDE_ROOT BrainError (spec/cli.md §3.6.4).
+ */
+export async function resolveWritableTarget(rootDirectory, targetPath) {
+    const root = await realpath(resolve(rootDirectory));
+    const target = isAbsolute(targetPath) ? resolve(targetPath) : resolve(root, targetPath);
+    assertContained(root, target);
+    const parent = await realpath(dirname(target));
+    assertContained(root, parent);
+    try {
+        const targetMetadata = await lstat(target);
+        if (targetMetadata.isSymbolicLink()) {
+            throw new BrainError("OUTSIDE_ROOT", `Refusing to replace a symbolic link: ${target}`);
+        }
+    }
+    catch (error) {
+        if (!isNodeError(error) || error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+    return { root, target, parent };
+}
+/**
+ * Atomically replace a file inside a brain directory.
+ *
+ * The parent directory must already exist. Existing symlink targets are rejected,
+ * and the real parent path is checked to prevent writes through escaping symlinks.
+ */
+export async function atomicWriteFile(brainDirectory, targetPath, data) {
+    const { root: brainRoot, target, parent } = await resolveWritableTarget(brainDirectory, targetPath);
+    const temporary = resolve(parent, `.${basename(target)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+    assertContained(brainRoot, temporary);
+    let handle;
+    try {
+        handle = await open(temporary, "wx", 0o600);
+        await handle.writeFile(data);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await rename(temporary, target);
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+}
+/**
+ * Atomically create a file, refusing to replace anything that appeared after the caller scanned
+ * the directory. Linking the completed temporary file is exclusive: unlike rename, it fails with
+ * EEXIST rather than overwriting a concurrent writer's file.
+ */
+export async function atomicCreateFile(brainDirectory, targetPath, data, linkFile = link) {
+    const { root: brainRoot, target, parent } = await resolveWritableTarget(brainDirectory, targetPath);
+    const temporary = resolve(parent, `.${basename(target)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+    assertContained(brainRoot, temporary);
+    let handle;
+    try {
+        handle = await open(temporary, "wx", 0o600);
+        await handle.writeFile(data);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        try {
+            await linkFile(temporary, target);
+        }
+        catch (error) {
+            if (!isNodeError(error) || !["ENOTSUP", "EPERM", "ENOSYS", "EXDEV"].includes(error.code ?? "")) {
+                if (isNodeError(error) && error.code === "EEXIST")
+                    throw new BrainError("WRITE_CONFLICT", `A file appeared while creating ${targetPath}`);
+                throw error;
+            }
+            const direct = await open(target, "wx", 0o600).catch((openError) => {
+                if (isNodeError(openError) && openError.code === "EEXIST")
+                    throw new BrainError("WRITE_CONFLICT", `A file appeared while creating ${targetPath}`);
+                throw openError;
+            });
+            try {
+                await direct.writeFile(data);
+                await direct.sync();
+            }
+            catch (writeError) {
+                await unlink(target).catch(() => undefined);
+                throw writeError;
+            }
+            finally {
+                await direct.close().catch(() => undefined);
+            }
+        }
+        await unlink(temporary).catch(() => undefined);
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+}
+/**
+ * Create a directory (and parents) inside a root, refusing anything that resolves outside it.
+ * The nearest existing ancestor is checked with realpath so a symlinked folder cannot escape.
+ */
+export async function ensureDirectory(rootDirectory, targetPath) {
+    const root = await realpath(resolve(rootDirectory));
+    const target = isAbsolute(targetPath) ? resolve(targetPath) : resolve(root, targetPath);
+    assertContained(root, target);
+    let existing = target;
+    while (true) {
+        try {
+            assertContained(root, await realpath(existing));
+            break;
+        }
+        catch (error) {
+            if (!isNodeError(error) || error.code !== "ENOENT")
+                throw error;
+            existing = dirname(existing);
+        }
+    }
+    await mkdir(target, { recursive: true });
+}
+/** Throw unless target is the brain root or one of its descendants. */
+export function assertPathInsideBrain(brainRoot, target) {
+    assertContained(resolve(brainRoot), resolve(target));
+}
+function assertContained(root, target) {
+    const pathFromRoot = relative(root, target);
+    if (pathFromRoot === "")
+        return;
+    if (pathFromRoot === ".." || pathFromRoot.startsWith(`..${sep}`) || isAbsolute(pathFromRoot)) {
+        throw new BrainError("OUTSIDE_ROOT", `Refusing to write outside the brain directory: ${target}`);
+    }
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/lib/ids.js

@@ -0,0 +1,51 @@
+import { randomBytes as nodeRandomBytes } from "node:crypto";
+export const ID_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
+export const ID_PREFIXES = [
+    "area",
+    "gol",
+    "prj",
+    "per",
+    "org",
+    "mtg",
+    "dec",
+    "que",
+    "con",
+    "src",
+    "mem",
+    "prp",
+    "vw",
+];
+const ID_LENGTH = 8;
+/** Generate a stable-format note ID, retrying when the candidate already exists. */
+export function generateId(prefix, existingIds, randomBytes = nodeRandomBytes) {
+    while (true) {
+        const bytes = randomBytes(ID_LENGTH);
+        if (bytes.length !== ID_LENGTH) {
+            throw new Error(`ID random source returned ${bytes.length} bytes; expected ${ID_LENGTH}`);
+        }
+        let suffix = "";
+        for (const byte of bytes) {
+            suffix += ID_ALPHABET[byte & 31];
+        }
+        const candidate = `${prefix}-${suffix}`;
+        if (!existingIds.has(candidate)) {
+            return candidate;
+        }
+    }
+}
+/** ID prefix of each note type (spec/schema.md §1). */
+export const TYPE_PREFIX = {
+    area: "area",
+    goal: "gol",
+    project: "prj",
+    person: "per",
+    org: "org",
+    meeting: "mtg",
+    decision: "dec",
+    question: "que",
+    concept: "con",
+    source: "src",
+    memory: "mem",
+    proposal: "prp",
+    view: "vw",
+};