@binarycheater/research-sidecar 0.1.0

package/dist-server/lib/researchGraphManifest.js

@@ -0,0 +1,221 @@
+import { access, readFile } from "node:fs/promises";
+import { dirname, extname, isAbsolute, join } from "node:path";
+import YAML from "yaml";
+import { resolveWorkspacePath, toWorkspaceRelativePath } from "./files.js";
+const DEFAULT_MANIFEST_PATH = "research/graph.yaml";
+const NODE_TYPES = new Set(["question", "claim", "evidence", "method", "concept", "source", "task", "output"]);
+const EDGE_KINDS = new Set(["decomposes", "answers", "supports", "contradicts", "depends_on", "operationalizes", "cites", "leads_to"]);
+const STATUSES = new Set(["active", "draft", "blocked", "done"]);
+const LAYOUTS = new Set(["LR", "TB"]);
+export async function loadResearchGraphManifest(workspaceRoot, manifestPath = DEFAULT_MANIFEST_PATH) {
+    const fullPath = resolveWorkspacePath(workspaceRoot, manifestPath);
+    const manifest = parseYamlRecord(await readFile(fullPath, "utf8"), manifestPath);
+    const manifestDir = dirname(manifestPath);
+    const rootId = requiredString(manifest.root, "root");
+    const nodes = asArray(manifest.nodes, "nodes");
+    const edges = asArray(manifest.edges ?? [], "edges");
+    const warnings = [];
+    const graphNodes = [];
+    for (const node of nodes) {
+        graphNodes.push(await normalizeNode(workspaceRoot, manifestDir, node, warnings));
+    }
+    const nodeIds = new Set(graphNodes.map((node) => node.id));
+    if (!nodeIds.has(rootId)) {
+        throw new Error(`Graph root ${rootId} does not match any node id.`);
+    }
+    const graphEdges = edges.map((edge) => normalizeEdge(edge, nodeIds));
+    const ui = normalizeUi(manifest.ui);
+    return {
+        rootId,
+        sourcePath: manifestPath,
+        nodes: graphNodes,
+        edges: graphEdges,
+        warnings,
+        ...(ui ? { ui } : {})
+    };
+}
+async function normalizeNode(workspaceRoot, manifestDir, input, warnings) {
+    const id = requiredString(input.id, "node.id");
+    const linkedFiles = normalizeManifestLinkedFiles(workspaceRoot, manifestDir, input.file, input.files);
+    const primaryFile = linkedFiles[0]?.path;
+    const frontmatter = primaryFile && isMarkdownPath(primaryFile) ? await readNodeFrontmatter(workspaceRoot, primaryFile) : {};
+    const frontmatterFiles = linkedFiles.length ? [] : normalizeManifestLinkedFiles(workspaceRoot, manifestDir, frontmatter.file, frontmatter.files);
+    const files = linkedFiles.length ? linkedFiles : frontmatterFiles;
+    const file = files[0]?.path;
+    const frontmatterId = optionalString(frontmatter.id);
+    if (frontmatterId && frontmatterId !== id) {
+        throw new Error(`Frontmatter id ${frontmatterId} does not match graph node ${id}.`);
+    }
+    const manifestTags = asStringArray(input.tags);
+    const frontmatterTags = asStringArray(frontmatter.tags);
+    const node = {
+        id,
+        title: optionalString(input.title) || optionalString(frontmatter.title) || id,
+        type: normalizeNodeType(optionalString(input.type) || optionalString(frontmatter.type), id),
+        ...(file ? { file } : {}),
+        ...(files.length ? { files } : {}),
+        ...optionalField("summary", optionalString(input.summary) || optionalString(frontmatter.summary)),
+        ...optionalStatus(optionalString(input.status) || optionalString(frontmatter.status)),
+        ...(manifestTags.length || frontmatterTags.length ? { tags: manifestTags.length ? manifestTags : frontmatterTags } : {})
+    };
+    if (files.length) {
+        for (const linked of files) {
+            linked.fileExists = await fileExists(workspaceRoot, linked.path);
+            if (!linked.fileExists) {
+                warnings.push(`Missing file for node ${id}: ${linked.path}`);
+            }
+        }
+        node.fileExists = files[0].fileExists;
+    }
+    return node;
+}
+function normalizeEdge(input, nodeIds) {
+    const from = requiredString(input.from, "edge.from");
+    const to = requiredString(input.to, "edge.to");
+    const kind = normalizeEdgeKind(input.kind);
+    if (!nodeIds.has(from)) {
+        throw new Error(`Edge source ${from} does not match any node id.`);
+    }
+    if (!nodeIds.has(to)) {
+        throw new Error(`Edge target ${to} does not match any node id.`);
+    }
+    return {
+        id: optionalString(input.id) || `${from}->${to}:${kind}`,
+        from,
+        to,
+        kind,
+        ...optionalField("label", input.label)
+    };
+}
+function normalizeUi(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const input = value;
+    const expanded = asStringArray(input.expanded);
+    const layout = optionalString(input.layout);
+    return {
+        ...(expanded.length ? { expanded } : {}),
+        ...(layout && LAYOUTS.has(layout) ? { layout: layout } : {})
+    };
+}
+async function readNodeFrontmatter(workspaceRoot, path) {
+    try {
+        const raw = await readFile(resolveWorkspacePath(workspaceRoot, path), "utf8");
+        const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+        return match ? parseYamlRecord(match[1], path) : {};
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return {};
+        throw error;
+    }
+}
+function normalizeManifestLinkedPath(workspaceRoot, manifestDir, value) {
+    if (!value)
+        return undefined;
+    if (isAbsolute(value)) {
+        const workspaceRelative = value.replace(/^\/+/, "");
+        return toWorkspaceRelativePath(workspaceRoot, resolveWorkspacePath(workspaceRoot, workspaceRelative));
+    }
+    const candidate = join(manifestDir, value);
+    return toWorkspaceRelativePath(workspaceRoot, resolveWorkspacePath(workspaceRoot, candidate));
+}
+function normalizeManifestLinkedFiles(workspaceRoot, manifestDir, fileValue, filesValue) {
+    const out = [];
+    const seen = new Set();
+    function add(pathValue, titleValue) {
+        const path = normalizeManifestLinkedPath(workspaceRoot, manifestDir, optionalString(pathValue));
+        if (!path || seen.has(path))
+            return;
+        seen.add(path);
+        out.push({
+            path,
+            ...optionalField("title", titleValue)
+        });
+    }
+    add(fileValue);
+    if (Array.isArray(filesValue)) {
+        for (const item of filesValue) {
+            if (typeof item === "string") {
+                add(item);
+            }
+            else if (item && typeof item === "object" && !Array.isArray(item)) {
+                const record = item;
+                add(record.path ?? record.file, record.title);
+            }
+        }
+    }
+    return out;
+}
+function parseYamlRecord(source, label) {
+    let parsed;
+    try {
+        parsed = YAML.parse(source);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`${label} is not valid YAML: ${message}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`${label} must contain a YAML object.`);
+    }
+    return parsed;
+}
+function requiredString(value, label) {
+    const normalized = optionalString(value);
+    if (!normalized) {
+        throw new Error(`${label} is required.`);
+    }
+    return normalized;
+}
+function optionalString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function normalizeNodeType(value, id) {
+    const type = optionalString(value);
+    if (!type || !NODE_TYPES.has(type)) {
+        throw new Error(`Node ${id} has invalid type ${type || "missing"}.`);
+    }
+    return type;
+}
+function normalizeEdgeKind(value) {
+    const kind = optionalString(value);
+    if (!kind || !EDGE_KINDS.has(kind)) {
+        throw new Error(`Edge has invalid kind ${kind || "missing"}.`);
+    }
+    return kind;
+}
+function optionalField(key, value) {
+    const normalized = optionalString(value);
+    return normalized ? { [key]: normalized } : {};
+}
+function optionalStatus(value) {
+    const status = optionalString(value);
+    return status && STATUSES.has(status) ? { status: status } : {};
+}
+function asArray(value, label) {
+    if (!Array.isArray(value)) {
+        throw new Error(`${label} must be an array.`);
+    }
+    return value;
+}
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string" && item.trim().length > 0).map((item) => item.trim());
+}
+async function fileExists(workspaceRoot, path) {
+    try {
+        await access(resolveWorkspacePath(workspaceRoot, path));
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function isMarkdownPath(path) {
+    const extension = extname(path).toLowerCase();
+    return extension === ".md" || extension === ".markdown";
+}

package/dist-server/lib/sidebarLayout.js

@@ -0,0 +1,17 @@
+export const DEFAULT_SIDEBAR_WIDTH = 328;
+export const MIN_SIDEBAR_WIDTH = 248;
+export const MAX_SIDEBAR_WIDTH = 560;
+export const DEFAULT_SIDEBAR_SPLIT = 50;
+export const MIN_SIDEBAR_SPLIT = 24;
+export const MAX_SIDEBAR_SPLIT = 76;
+export function clampSidebarWidth(width, viewportWidth) {
+    if (!Number.isFinite(width))
+        return DEFAULT_SIDEBAR_WIDTH;
+    const viewportMax = Math.max(MIN_SIDEBAR_WIDTH, Math.floor(viewportWidth * 0.48));
+    return Math.min(Math.max(width, MIN_SIDEBAR_WIDTH), Math.min(MAX_SIDEBAR_WIDTH, viewportMax));
+}
+export function clampSidebarSplit(split) {
+    if (!Number.isFinite(split))
+        return DEFAULT_SIDEBAR_SPLIT;
+    return Math.min(Math.max(split, MIN_SIDEBAR_SPLIT), MAX_SIDEBAR_SPLIT);
+}

package/dist-server/lib/store.js

@@ -0,0 +1,190 @@
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { detectFilePreviewFormat } from "./files.js";
+import { DEFAULT_MODEL, DEFAULT_REVIEW_PROMPT } from "./prompt.js";
+export class JsonSessionStore {
+    indexFile;
+    options;
+    constructor(indexFile, options = {}) {
+        this.indexFile = indexFile;
+        this.options = options;
+    }
+    async listSessions() {
+        const index = await this.readIndex();
+        return index.sessions
+            .slice()
+            .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    }
+    async createSession(input = {}) {
+        const now = new Date().toISOString();
+        const session = {
+            id: crypto.randomUUID(),
+            title: input.title?.trim() || "Untitled review",
+            createdAt: now,
+            updatedAt: now,
+            manualContext: "",
+            reviewPrompt: DEFAULT_REVIEW_PROMPT,
+            model: input.model || DEFAULT_MODEL,
+            apiMode: input.apiMode || "responses",
+            files: [],
+            messages: []
+        };
+        const index = await this.readIndex();
+        index.sessions.push(toIndexEntry(session));
+        await this.writeSession(session);
+        await this.writeIndex(index);
+        return session;
+    }
+    async getSession(id) {
+        try {
+            return await this.readSession(id);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return null;
+            throw error;
+        }
+    }
+    async updateSession(id, patch) {
+        return this.mutateSession(id, (session) => {
+            Object.assign(session, compactPatch(patch));
+        });
+    }
+    async addMessage(sessionId, input) {
+        return this.mutateSession(sessionId, (session) => {
+            session.messages.push({
+                id: crypto.randomUUID(),
+                createdAt: new Date().toISOString(),
+                ...input
+            });
+        });
+    }
+    async replaceMessageAndTruncate(sessionId, messageId, content) {
+        return this.mutateSession(sessionId, (session) => {
+            const index = session.messages.findIndex((message) => message.id === messageId);
+            if (index < 0) {
+                throw new Error("Message not found.");
+            }
+            if (session.messages[index].role !== "user") {
+                throw new Error("Only user messages can be edited.");
+            }
+            session.messages[index] = {
+                ...session.messages[index],
+                content,
+                createdAt: new Date().toISOString()
+            };
+            session.messages = session.messages.slice(0, index + 1);
+        });
+    }
+    async addFile(sessionId, input) {
+        return this.mutateSession(sessionId, (session) => {
+            const previewFormat = input.format && input.mimeType ? { format: input.format, mimeType: input.mimeType } : detectFilePreviewFormat(input.path);
+            session.files.push({
+                id: input.id || crypto.randomUUID(),
+                addedAt: input.addedAt || new Date().toISOString(),
+                path: input.path,
+                content: input.content,
+                bytes: input.bytes,
+                ...previewFormat
+            });
+        });
+    }
+    async removeFile(sessionId, fileId) {
+        return this.mutateSession(sessionId, (session) => {
+            session.files = session.files.filter((file) => file.id !== fileId);
+        });
+    }
+    async mutateSession(id, mutate) {
+        const session = await this.getSession(id);
+        if (!session)
+            throw new Error("Session not found.");
+        mutate(session);
+        session.updatedAt = new Date().toISOString();
+        await this.writeSession(session);
+        await this.upsertIndex(session);
+        return session;
+    }
+    async readIndex() {
+        try {
+            const raw = await readFile(this.indexFile, "utf8");
+            return JSON.parse(raw);
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                const migrated = await this.migrateLegacyFile();
+                if (migrated)
+                    return migrated;
+                return { sessions: [] };
+            }
+            throw error;
+        }
+    }
+    async writeIndex(index) {
+        await atomicWriteJson(this.indexFile, index);
+    }
+    async readSession(id) {
+        const raw = await readFile(this.sessionPath(id), "utf8");
+        return JSON.parse(raw);
+    }
+    async writeSession(session) {
+        await atomicWriteJson(this.sessionPath(session.id), session);
+    }
+    async upsertIndex(session) {
+        const index = await this.readIndex();
+        const next = toIndexEntry(session);
+        const existing = index.sessions.findIndex((item) => item.id === session.id);
+        if (existing >= 0)
+            index.sessions[existing] = next;
+        else
+            index.sessions.push(next);
+        await this.writeIndex(index);
+    }
+    sessionPath(id) {
+        return join(dirname(this.indexFile), `${id}.json`);
+    }
+    async migrateLegacyFile() {
+        if (!this.options.legacyFile)
+            return null;
+        try {
+            const raw = await readFile(this.options.legacyFile, "utf8");
+            const legacy = JSON.parse(raw);
+            const sessions = Array.isArray(legacy.sessions) ? legacy.sessions : [];
+            const index = { sessions: sessions.map(toIndexEntry) };
+            await Promise.all(sessions.map((session) => this.writeSession(session)));
+            await this.writeIndex(index);
+            return index;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return null;
+            throw error;
+        }
+    }
+}
+async function atomicWriteJson(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.${crypto.randomUUID()}.tmp`;
+    try {
+        await writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`);
+        await rename(tmp, path);
+    }
+    catch (error) {
+        await unlink(tmp).catch(() => undefined);
+        throw error;
+    }
+}
+function toIndexEntry(session) {
+    return {
+        id: session.id,
+        title: session.title,
+        createdAt: session.createdAt,
+        updatedAt: session.updatedAt,
+        model: session.model,
+        apiMode: session.apiMode,
+        messageCount: session.messages.length,
+        fileCount: session.files.length
+    };
+}
+function compactPatch(patch) {
+    return Object.fromEntries(Object.entries(patch).filter(([, value]) => value !== undefined));
+}

package/dist-server/lib/tools.js

@@ -0,0 +1,205 @@
+import { readdir } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readWorkspaceFile, resolveWorkspacePath, writeWorkspaceFile } from "./files.js";
+import { loadSkillByReference } from "./workspaceMeta.js";
+const execFileAsync = promisify(execFile);
+const DEFAULT_ALLOWED_WRITE_EXTENSIONS = [".md", ".markdown", ".html", ".htm", ".yaml", ".yml"];
+export function createWorkspaceTools(workspaceRoot, options = {}) {
+    const allowedWriteExtensions = options.allowedWriteExtensions?.length ? options.allowedWriteExtensions : DEFAULT_ALLOWED_WRITE_EXTENSIONS;
+    return {
+        definitions: [
+            {
+                type: "function",
+                function: {
+                    name: "list_workspace_files",
+                    description: "List workspace files matching a simple substring or glob-like suffix pattern.",
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            pattern: { type: "string", description: "Optional substring or simple pattern like notes/*.md." }
+                        },
+                        additionalProperties: false
+                    }
+                }
+            },
+            {
+                type: "function",
+                function: {
+                    name: "read_workspace_file",
+                    description: "Read a UTF-8 text file by workspace-relative path.",
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            path: { type: "string", description: "Workspace-relative path to read." }
+                        },
+                        required: ["path"],
+                        additionalProperties: false
+                    }
+                }
+            },
+            {
+                type: "function",
+                function: {
+                    name: "read_workspace_files",
+                    description: "Read several UTF-8 text files by workspace-relative path in one call. Prefer this over repeated single-file reads when comparing or reviewing multiple files.",
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            paths: {
+                                type: "array",
+                                items: { type: "string" },
+                                minItems: 1,
+                                maxItems: 8,
+                                description: "Workspace-relative paths to read."
+                            }
+                        },
+                        required: ["paths"],
+                        additionalProperties: false
+                    }
+                }
+            },
+            {
+                type: "function",
+                function: {
+                    name: "write_workspace_file",
+                    description: "Write a UTF-8 workspace document. This tool is restricted to configured document extensions only and must not be used for source code files.",
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            path: {
+                                type: "string",
+                                description: `Workspace-relative path to write. Allowed extensions: ${allowedWriteExtensions.join(", ")}.`
+                            },
+                            content: { type: "string", description: "Full file content to write." }
+                        },
+                        required: ["path", "content"],
+                        additionalProperties: false
+                    }
+                }
+            },
+            {
+                type: "function",
+                function: {
+                    name: "get_git_diff",
+                    description: "Return the current git diff for the workspace, optionally scoped to a path.",
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            path: { type: "string", description: "Optional workspace-relative path to diff." }
+                        },
+                        additionalProperties: false
+                    }
+                }
+            },
+            {
+                type: "function",
+                function: {
+                    name: "load_skill",
+                    description: "Load the full SKILL.md instructions for a discovered workspace skill by exact skill name or workspace-relative SKILL.md path.",
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string", description: "Exact skill name, such as scholar-mode." },
+                            path: { type: "string", description: "Workspace-relative path to a SKILL.md file." }
+                        },
+                        additionalProperties: false
+                    }
+                }
+            }
+        ],
+        async execute(name, rawArgs) {
+            const args = parseArgs(rawArgs);
+            if (name === "list_workspace_files") {
+                const pattern = typeof args.pattern === "string" ? args.pattern : "";
+                const files = await listFiles(workspaceRoot);
+                return files.filter((file) => matchesPattern(file, pattern)).slice(0, 200).join("\n") || "No files matched.";
+            }
+            if (name === "read_workspace_file") {
+                const path = requireString(args.path, "path");
+                const snapshot = await readWorkspaceFile(workspaceRoot, path);
+                return snapshot.content;
+            }
+            if (name === "read_workspace_files") {
+                const paths = requireStringArray(args.paths, "paths").slice(0, 8);
+                const snapshots = await Promise.all(paths.map((path) => readWorkspaceFile(workspaceRoot, path)));
+                return snapshots.map((snapshot) => `## ${snapshot.path}\n\n${snapshot.content}`).join("\n\n---\n\n");
+            }
+            if (name === "write_workspace_file") {
+                const path = requireString(args.path, "path");
+                const content = requireContent(args.content);
+                const result = await writeWorkspaceFile(workspaceRoot, path, content, allowedWriteExtensions);
+                return `Wrote ${result.path} (${result.bytes} bytes).`;
+            }
+            if (name === "get_git_diff") {
+                const path = typeof args.path === "string" && args.path.trim() ? args.path.trim() : null;
+                if (path) {
+                    resolveWorkspacePath(workspaceRoot, path);
+                }
+                const commandArgs = ["diff", "--", ...(path ? [path] : [])];
+                const { stdout } = await execFileAsync("git", commandArgs, { cwd: workspaceRoot, maxBuffer: 1_000_000 });
+                return stdout || "No git diff.";
+            }
+            if (name === "load_skill") {
+                const reference = typeof args.name === "string" && args.name.trim() ? args.name : args.path;
+                const snapshot = await loadSkillByReference(workspaceRoot, requireString(reference, "name or path"));
+                return snapshot.content;
+            }
+            throw new Error(`Unknown tool: ${name}`);
+        }
+    };
+}
+function parseArgs(rawArgs) {
+    if (typeof rawArgs === "string") {
+        return rawArgs.trim() ? JSON.parse(rawArgs) : {};
+    }
+    return rawArgs || {};
+}
+function requireString(value, name) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`${name} is required.`);
+    }
+    return value.trim();
+}
+function requireContent(value) {
+    if (typeof value !== "string") {
+        throw new Error("content is required.");
+    }
+    return value;
+}
+function requireStringArray(value, name) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new Error(`${name} must be a non-empty array.`);
+    }
+    return value.map((item, index) => requireString(item, `${name}[${index}]`));
+}
+async function listFiles(root, dir = "") {
+    const full = join(root, dir);
+    const entries = await readdir(full, { withFileTypes: true });
+    const results = [];
+    for (const entry of entries) {
+        if (entry.name === ".git" || entry.name === ".side" || entry.name === "node_modules" || entry.name === "dist" || entry.name === "dist-server") {
+            continue;
+        }
+        const rel = dir ? `${dir}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            results.push(...(await listFiles(root, rel)));
+        }
+        else if (entry.isFile()) {
+            results.push(relative(root, join(root, rel)));
+        }
+    }
+    return results.sort();
+}
+function matchesPattern(file, pattern) {
+    if (!pattern.trim()) {
+        return true;
+    }
+    const normalized = pattern.replace(/^\.\//, "");
+    if (normalized.includes("*")) {
+        const [prefix, suffix] = normalized.split("*", 2);
+        return file.startsWith(prefix) && file.endsWith(suffix || "");
+    }
+    return file.includes(normalized);
+}

package/dist-server/lib/types.js

@@ -0,0 +1 @@
+export {};