ultimate-brain 0.0.0-stage → 0.2.0

package/dist/commands/sync.js

@@ -0,0 +1,53 @@
+import { readJsonInput } from "../lib/input.js";
+import { applyPlan, buildPlan, parsePlan, parseSnapshot, record, render, renderTasks } from "../lib/sync.js";
+import { Workspace } from "../lib/workspace.js";
+import { BrainError } from "../lib/errors.js";
+import { lintWarnings } from "../lib/warnings.js";
+export const syncPlanCommand = {
+    name: "sync plan", usage: "brain sync plan --input <snapshot|-> [--json]", summary: "Compare a Notion snapshot with the brain without writing.", options: { input: "string" }, maxPositionals: 0, needsBrain: true,
+    async run({ args, brain }) { const input = args.options.input; if (input === undefined)
+        throw new BrainError("USAGE", "sync plan needs --input"); const workspace = await Workspace.open(brain); const plan = buildPlan(workspace, parseSnapshot(await readJsonInput(input, "sync plan"))); return { data: plan, human: `${plan.create.length} creates, ${plan.updates.length} updates, ${plan.corrections.length} corrections\n` }; },
+};
+export const syncApplyCommand = {
+    name: "sync apply", usage: "brain sync apply --input <plan|-> [--record-only] [--dry-run] [--json]", summary: "Apply a sync plan using atomic per-item writes.", options: { input: "string", "record-only": "boolean", "dry-run": "boolean" }, maxPositionals: 0, needsBrain: true,
+    async run({ args, brain, now }) { const input = args.options.input; if (input === undefined)
+        throw new BrainError("USAGE", "sync apply needs --input"); const workspace = await Workspace.open(brain); const data = applyPlan(workspace, parsePlan(await readJsonInput(input, "sync apply")), now, args.options["record-only"] === true); const warnings = lintWarnings(workspace.warnings()); const dryRun = args.options["dry-run"] === true; if (!dryRun)
+        await workspace.commit(data.log, now); const { log: _log, ...output } = data; const failed = Number(data.summary.failed ?? 0); return { data: { dry_run: dryRun, ...output }, warnings, exitCode: failed > 0 ? 1 : 0, human: `${failed} failed items\n` }; },
+};
+export const syncRenderCommand = {
+    name: "sync render", usage: "brain sync render (--changed | --ids <id>[,<id>…]) [--plan <plan.json>] [--json]", summary: "Render Notion payloads without writing.", options: { changed: "boolean", ids: "string", plan: "string" }, maxPositionals: 0, needsBrain: true,
+    async run({ args, brain, now }) {
+        const changed = args.options.changed === true;
+        const idsText = args.options.ids;
+        if (changed === (idsText !== undefined))
+            throw new BrainError("USAGE", "provide exactly one of --changed or --ids");
+        const workspace = await Workspace.open(brain);
+        const ids = idsText === undefined ? undefined : idsText.split(",").map((id) => id.trim()).filter(Boolean);
+        if (ids !== undefined)
+            for (const id of ids)
+                if (workspace.get(id) === undefined)
+                    throw new BrainError("UNKNOWN_ID", `No note with id ${id}`);
+        const held = new Map();
+        const planPath = args.options.plan;
+        if (planPath !== undefined)
+            for (const item of parsePlan(await readJsonInput(planPath, "sync render")).conflicts)
+                if (item.code === "BOTH_CHANGED" && typeof item.brain_id === "string" && typeof item.property === "string") {
+                    const set = held.get(item.brain_id) ?? new Set();
+                    set.add(item.property);
+                    held.set(item.brain_id, set);
+                }
+        const data = render(workspace, now, ids, held);
+        return { data: { items: data.items, errors: data.errors }, warnings: data.warnings, exitCode: data.errors.length > 0 ? 1 : 0, human: `${data.items.length} payloads\n` };
+    },
+};
+export const syncTasksCommand = {
+    name: "sync tasks", usage: "brain sync tasks --meeting <mtg-id> --input <file|-> [--json]", summary: "Render action-item task payloads for a meeting.", options: { meeting: "string", input: "string" }, maxPositionals: 0, needsBrain: true,
+    async run({ args, brain }) { const meeting = args.options.meeting; const input = args.options.input; if (meeting === undefined || input === undefined)
+        throw new BrainError("USAGE", "sync tasks needs --meeting and --input"); return { data: renderTasks(await Workspace.open(brain), meeting, await readJsonInput(input, "sync tasks")), human: "Task payloads rendered.\n" }; },
+};
+export const syncRecordCommand = {
+    name: "sync record", usage: "brain sync record --input <file|-> [--dry-run] [--json]", summary: "Record successful Notion publication results.", options: { input: "string", "dry-run": "boolean" }, maxPositionals: 0, needsBrain: true,
+    async run({ args, brain, now }) { const input = args.options.input; if (input === undefined)
+        throw new BrainError("USAGE", "sync record needs --input"); const workspace = await Workspace.open(brain); const data = record(workspace, await readJsonInput(input, "sync record")); const records = data.records; const dryRun = args.options["dry-run"] === true; if (!dryRun)
+        await workspace.commit([], now); const failed = records.filter((item) => item.result === "failed").length; return { data: { dry_run: dryRun, ...data }, exitCode: failed > 0 ? 1 : 0, human: `${records.length} records\n` }; },
+};

package/dist/commands/upgrade.js

@@ -0,0 +1,143 @@
+import { lstat, readdir, readFile, unlink } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { atomicWriteFile, ensureDirectory } from "../lib/fs-safe.js";
+import { appendLog } from "../lib/log.js";
+import { assertPlainPath, listShippedSkillFiles } from "../lib/skills.js";
+const TEMPLATE_ROOT = fileURLToPath(new URL("../../templates/brain/", import.meta.url));
+const PACKAGE_JSON = fileURLToPath(new URL("../../package.json", import.meta.url));
+const START = /^<!-- ultimate-brain:rules:start\b[^\n]*-->$/gm;
+const END = /^<!-- ultimate-brain:rules:end -->$/gm;
+/** `brain upgrade` (spec/cli.md §5.15): bring the product-owned files of a brain up to the installed package. */
+export const upgradeCommand = {
+    name: "upgrade",
+    usage: "brain upgrade [--dry-run] [--json]",
+    summary: "Update the brain's product-owned AGENTS.md block and skills to the installed version.",
+    options: { "dry-run": "boolean" },
+    maxPositionals: 0,
+    needsBrain: true,
+    async run({ args, brain, now }) {
+        const root = brain.root;
+        const warnings = [];
+        const changes = [];
+        let unchanged = 0;
+        // Every check runs before the first write, so a refusal leaves the brain untouched.
+        const template = await readFile(join(TEMPLATE_ROOT, "AGENTS.md"), "utf8");
+        await assertPlainPath(root, "AGENTS.md");
+        const current = await readOptional(join(root, "AGENTS.md"));
+        if (current === null)
+            changes.push({ path: "AGENTS.md", action: "created", content: template });
+        else {
+            const block = rulesBlock(template);
+            const own = rulesBlock(current);
+            if (own === undefined) {
+                changes.push({ path: "AGENTS.md", action: "skipped" });
+                warnings.push({ code: "AGENTS_BLOCK_NOT_FOUND", message: "AGENTS.md has no single ultimate-brain rules block; left unchanged." });
+            }
+            else if (own === block)
+                unchanged += 1;
+            else
+                changes.push({ path: "AGENTS.md", action: "updated", content: current.replace(own, () => block) });
+        }
+        if (!(await exists(join(root, "CLAUDE.md"))))
+            changes.push({ path: "CLAUDE.md", action: "created", content: "@AGENTS.md\n" });
+        else
+            unchanged += 1;
+        // Skills (decision 0029): shipped files are product-owned, inside the folders of shipped skills only.
+        const shipped = await listShippedSkillFiles();
+        const shippedPaths = new Set(shipped.map((file) => file.relative));
+        for (const name of new Set(shipped.map((file) => file.relative.split("/")[0])))
+            await assertPlainPath(root, `.agents/skills/${name}`, "folder");
+        for (const file of shipped) {
+            const path = `.agents/skills/${file.relative}`;
+            await assertPlainPath(root, path);
+            const existing = await readOptionalBuffer(join(root, path));
+            if (existing === null)
+                changes.push({ path, action: "created", content: file.content });
+            else if (existing.equals(file.content))
+                unchanged += 1;
+            else
+                changes.push({ path, action: "updated", content: file.content });
+        }
+        for (const name of new Set(shipped.map((file) => file.relative.split("/")[0]))) {
+            for (const file of await listFiles(join(root, ".agents/skills", name))) {
+                const inSkills = `${name}/${file}`;
+                await assertPlainPath(root, `.agents/skills/${inSkills}`);
+                if (!shippedPaths.has(inSkills))
+                    changes.push({ path: `.agents/skills/${inSkills}`, action: "removed" });
+            }
+        }
+        changes.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+        const written = changes.filter((change) => change.action !== "skipped");
+        const version = JSON.parse(await readFile(PACKAGE_JSON, "utf8")).version;
+        const dryRun = args.options["dry-run"] === true;
+        if (!dryRun && written.length > 0) {
+            for (const change of written) {
+                if (change.action === "removed") {
+                    await unlink(join(root, change.path));
+                    continue;
+                }
+                await ensureDirectory(root, dirname(change.path));
+                await atomicWriteFile(root, change.path, change.content);
+            }
+            await appendLog(root, now, [{ op: "upgrade", id: "-", title: version, pairs: [["files", written.length]] }]);
+        }
+        return {
+            warnings,
+            data: { dry_run: dryRun, version, files: changes.map(({ path, action }) => ({ path, action })), unchanged },
+            human: `${written.length} files ${dryRun ? "would change" : "changed"}, ${unchanged} unchanged\n`,
+        };
+    },
+};
+/** The text from the rules start marker through the end marker, when exactly one well-ordered pair exists. */
+function rulesBlock(text) {
+    const starts = [...text.matchAll(START)];
+    const ends = [...text.matchAll(END)];
+    if (starts.length !== 1 || ends.length !== 1 || ends[0].index < starts[0].index)
+        return undefined;
+    return text.slice(starts[0].index, ends[0].index + ends[0][0].length);
+}
+async function listFiles(folder) {
+    const files = [];
+    async function visit(current) {
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const path = join(current, entry.name);
+            if (entry.isDirectory())
+                await visit(path);
+            else
+                files.push(relative(folder, path).split(sep).join("/"));
+        }
+    }
+    await visit(folder);
+    return files;
+}
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readOptional(path) {
+    const buffer = await readOptionalBuffer(path);
+    return buffer === null ? null : buffer.toString("utf8");
+}
+async function readOptionalBuffer(path) {
+    try {
+        if (!(await lstat(path)).isFile())
+            return null;
+        return await readFile(path);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/commands/views.js

@@ -0,0 +1,111 @@
+import { BrainError } from "../lib/errors.js";
+import { serializeNewFile } from "../lib/frontmatter.js";
+import { generateId } from "../lib/ids.js";
+import { compareCodePoints } from "../lib/notes.js";
+import { formatDate, formatTimestamp } from "../lib/time.js";
+import { deriveView, generatedBlockRange, projectViewPath } from "../lib/views.js";
+import { Workspace } from "../lib/workspace.js";
+/** `brain views [--project <id>] [--check]` (spec/cli.md §5.9). */
+export const viewsCommand = {
+    name: "views",
+    usage: "brain views [--project <id>] [--check] [--json]",
+    summary: "Regenerate project briefs and decision logs while preserving user blocks.",
+    options: { project: "string", check: "boolean" },
+    maxPositionals: 0,
+    needsBrain: true,
+    async run({ args, brain, now }) {
+        const workspace = await Workspace.open(brain);
+        const requested = args.options.project;
+        let projects = workspace.notes.filter((note) => note.type === "project");
+        if (requested !== undefined) {
+            const project = workspace.get(requested);
+            if (project?.type !== "project")
+                throw new BrainError("UNKNOWN_ID", `No project with id ${requested}`);
+            projects = [project];
+        }
+        projects.sort((left, right) => compareCodePoints(left.path, right.path));
+        const written = [];
+        const created = [];
+        const unchanged = [];
+        const errors = [];
+        const ids = workspace.ids();
+        const check = args.options.check === true;
+        for (const project of projects) {
+            for (const kind of ["brief", "decision_log"]) {
+                const path = projectViewPath(project, kind);
+                const existing = workspace.notes.find((note) => note.path === path);
+                const derived = deriveView(project, kind, workspace.notes);
+                if (existing === undefined && workspace.exists(path)) {
+                    errors.push({ path, reason: "MARKERS_INVALID" });
+                    continue;
+                }
+                if (existing === undefined) {
+                    created.push(path);
+                    if (!check) {
+                        const id = generateId("vw", ids);
+                        ids.add(id);
+                        workspace.write(path, serializeNewFile(newViewAttributes(id, project, kind, derived.generatedFrom, now), `${derived.generatedBlock}\n\n<!-- @user:start -->\n<!-- @user:end -->\n`));
+                    }
+                    continue;
+                }
+                const range = existing.type === "view" && existing.attributes.project === project.id && existing.attributes.view_kind === kind
+                    ? generatedBlockRange(existing.body)
+                    : undefined;
+                if (range === undefined) {
+                    errors.push({ path, reason: "MARKERS_INVALID" });
+                    continue;
+                }
+                const currentFrom = Array.isArray(existing.attributes.generated_from) ? existing.attributes.generated_from : [];
+                const unchangedView = existing.body.slice(range.start, range.end) === derived.generatedBlock
+                    && sameStrings(currentFrom, derived.generatedFrom);
+                if (unchangedView) {
+                    unchanged.push(path);
+                    continue;
+                }
+                written.push(path);
+                if (!check) {
+                    const document = workspace.edit(existing);
+                    document.attributes.generated_from = derived.generatedFrom;
+                    document.attributes.generated_at = formatTimestamp(now);
+                    document.attributes.updated = formatDate(now);
+                    document.body = `${existing.body.slice(0, range.start)}${derived.generatedBlock}${existing.body.slice(range.end)}`;
+                    workspace.save(path, document);
+                }
+            }
+        }
+        if (!check && workspace.changedPaths.length > 0) {
+            const invalid = workspace.newErrors();
+            if (invalid.length > 0) {
+                throw new BrainError("INPUT_INVALID", `Generated views would add lint errors: ${invalid.map((issue) => `${issue.path} ${issue.rule}`).join(", ")}`);
+            }
+            await workspace.commit();
+        }
+        written.sort(compareCodePoints);
+        created.sort(compareCodePoints);
+        unchanged.sort(compareCodePoints);
+        errors.sort((left, right) => compareCodePoints(left.path, right.path));
+        const exitCode = errors.length > 0 || (check && (written.length > 0 || created.length > 0)) ? 1 : 0;
+        return {
+            data: { projects: projects.length, written, created, unchanged, errors, check },
+            exitCode,
+            human: errors.length > 0 ? `${errors.map((error) => `${error.path}: ${error.reason}`).join("\n")}\n` : "Views are current.\n",
+        };
+    },
+};
+function newViewAttributes(id, project, kind, generatedFrom, now) {
+    const suffix = kind === "brief" ? "brief" : "decision log";
+    return {
+        id,
+        type: "view",
+        title: `${String(project.attributes.title)} — ${suffix}`,
+        view_kind: kind,
+        project: project.id,
+        generated_from: generatedFrom,
+        generated_at: formatTimestamp(now),
+        created: formatDate(now),
+        updated: formatDate(now),
+    };
+}
+function sameStrings(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}