@binarycheater/research-sidecar 0.1.0

package/dist-server/server/index.js

@@ -0,0 +1,365 @@
+import express from "express";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildContextPacket } from "../lib/context.js";
+import { readWorkspaceFile } from "../lib/files.js";
+import { discoverGraphManifests } from "../lib/graphDiscovery.js";
+import { DEFAULT_REVIEW_PROMPT } from "../lib/prompt.js";
+import { loadResearchGraphManifest } from "../lib/researchGraphManifest.js";
+import { streamOpenAIReview } from "../lib/openaiProvider.js";
+import { JsonSessionStore } from "../lib/store.js";
+import { installBundledSkills } from "../lib/workspaceInstall.js";
+import { findInstructionFiles, loadTriggeredSkillFiles, scanWorkspaceSkills, selectSkillTriggers } from "../lib/workspaceMeta.js";
+import { loadConfig, updateGraphManifestPath } from "./config.js";
+const config = loadConfig();
+const store = new JsonSessionStore(config.dataFile, { legacyFile: resolve(process.cwd(), "data", "sessions.json") });
+const app = express();
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const clientDist = resolve(__dirname, "../../dist/client");
+app.use(express.json({ limit: "4mb" }));
+app.get("/api/config", (_req, res) => {
+    res.json(publicConfig());
+});
+app.patch("/api/config", (req, res, next) => {
+    try {
+        if (typeof req.body?.graphManifestPath === "string") {
+            updateGraphManifestPath(config, req.body.graphManifestPath);
+        }
+        res.json(publicConfig());
+    }
+    catch (error) {
+        next(error);
+    }
+});
+app.get("/api/graphs", async (_req, res, next) => {
+    try {
+        res.json({
+            current: config.graphManifestPath,
+            candidates: await discoverGraphManifests(config.workspaceRoot, config.graphManifestPath)
+        });
+    }
+    catch (error) {
+        next(error);
+    }
+});
+app.get("/api/workspace", async (_req, res, next) => {
+    try {
+        res.json({
+            instructionFiles: (await findInstructionFiles(config.workspaceRoot)).map(({ path, bytes }) => ({ path, bytes })),
+            skills: await scanWorkspaceSkills(config.workspaceRoot)
+        });
+    }
+    catch (error) {
+        next(error);
+    }
+});
+app.post("/api/workspace/skills/install", async (req, res, next) => {
+    try {
+        const result = await installBundledSkills(config.workspaceRoot, { force: Boolean(req.body?.force) });
+        res.json(result);
+    }
+    catch (error) {
+        next(error);
+    }
+});
+app.get("/api/workspace/file", async (req, res, next) => {
+    try {
+        const path = String(req.query.path || "");
+        const snapshot = await readWorkspaceFile(config.workspaceRoot, path);
+        res.json(snapshot);
+    }
+    catch (error) {
+        next(error);
+    }
+});
+app.get("/api/workspace/raw", async (req, res, next) => {
+    try {
+        const path = String(req.query.path || "");
+        const snapshot = await readWorkspaceFile(config.workspaceRoot, path);
+        res.type(snapshot.mimeType).send(snapshot.content);
+    }
+    catch (error) {
+        next(error);
+    }
+});
+app.get(/^\/api\/workspace\/raw-path\/(.+)$/, async (req, res, next) => {
+    try {
+        const path = decodeURIComponent(String(req.params[0] || ""));
+        const snapshot = await readWorkspaceFile(config.workspaceRoot, path);
+        res.type(snapshot.mimeType).send(snapshot.content);
+    }
+    catch (error) {
+        next(error);
+    }
+});
+app.get("/api/research-graph", async (_req, res, next) => {
+    try {
+        res.json(await loadResearchGraphManifest(config.workspaceRoot, config.graphManifestPath));
+    }
+    catch (error) {
+        next(error);
+    }
+});
+app.get("/api/sessions", async (_req, res, next) => {
+    try {
+        res.json(await store.listSessions());
+    }
+    catch (error) {
+        next(error);
+    }
+});
+app.post("/api/sessions", async (req, res, next) => {
+    try {
+        const session = await store.createSession({
+            title: req.body?.title,
+            model: req.body?.model || config.defaultModel,
+            apiMode: config.apiMode
+        });
+        res.status(201).json(session);
+    }
+    catch (error) {
+        next(error);
+    }
+});
+app.get("/api/sessions/:id", async (req, res, next) => {
+    try {
+        const session = await store.getSession(req.params.id);
+        if (!session) {
+            res.status(404).json({ error: "Session not found." });
+            return;
+        }
+        res.json(session);
+    }
+    catch (error) {
+        next(error);
+    }
+});
+app.patch("/api/sessions/:id", async (req, res, next) => {
+    try {
+        const session = await store.updateSession(req.params.id, {
+            title: req.body?.title,
+            manualContext: req.body?.manualContext,
+            reviewPrompt: req.body?.reviewPrompt || DEFAULT_REVIEW_PROMPT,
+            model: req.body?.model,
+            apiMode: config.apiMode
+        });
+        res.json(session);
+    }
+    catch (error) {
+        next(error);
+    }
+});
+app.post("/api/sessions/:id/messages/:messageId/edit", async (req, res, next) => {
+    try {
+        const content = String(req.body?.content || "").trim();
+        if (!content) {
+            res.status(400).json({ error: "Content is required." });
+            return;
+        }
+        const session = await store.replaceMessageAndTruncate(req.params.id, req.params.messageId, content);
+        res.json(session);
+    }
+    catch (error) {
+        next(error);
+    }
+});
+app.post("/api/sessions/:id/messages", async (req, res, next) => {
+    try {
+        const role = req.body?.role === "user" ? "user" : null;
+        const content = String(req.body?.content || "").trim();
+        if (!role || !content) {
+            res.status(400).json({ error: "A user message content is required." });
+            return;
+        }
+        const session = await store.addMessage(req.params.id, {
+            role,
+            content,
+            source: "manual"
+        });
+        res.status(201).json(session);
+    }
+    catch (error) {
+        next(error);
+    }
+});
+app.post("/api/sessions/:id/files", async (req, res, next) => {
+    try {
+        const snapshot = await readWorkspaceFile(config.workspaceRoot, req.body?.path || "");
+        const session = await store.addFile(req.params.id, snapshot);
+        res.status(201).json(session);
+    }
+    catch (error) {
+        next(error);
+    }
+});
+app.delete("/api/sessions/:id/files/:fileId", async (req, res, next) => {
+    try {
+        const session = await store.removeFile(req.params.id, req.params.fileId);
+        res.json(session);
+    }
+    catch (error) {
+        next(error);
+    }
+});
+app.post("/api/sessions/:id/stream", async (req, res, next) => {
+    const abortController = new AbortController();
+    req.on("aborted", () => abortController.abort());
+    res.on("close", () => {
+        if (!res.writableEnded) {
+            abortController.abort();
+        }
+    });
+    try {
+        const session = await store.getSession(req.params.id);
+        if (!session) {
+            res.status(404).json({ error: "Session not found." });
+            return;
+        }
+        const userMessage = String(req.body?.message || "").trim();
+        if (!userMessage) {
+            res.status(400).json({ error: "Message is required." });
+            return;
+        }
+        const model = String(req.body?.model || session.model || config.defaultModel);
+        const apiMode = config.apiMode;
+        const manualContext = String(req.body?.manualContext ?? session.manualContext);
+        const reviewPrompt = String(req.body?.reviewPrompt || session.reviewPrompt || DEFAULT_REVIEW_PROMPT);
+        const apiKey = config.openaiAPIKey;
+        if (!apiKey) {
+            res.status(400).json({ error: "OPENAI_API_KEY is not set." });
+            return;
+        }
+        await store.updateSession(session.id, { model, apiMode, manualContext, reviewPrompt });
+        const existingMessageId = typeof req.body?.existingMessageId === "string" ? req.body.existingMessageId : null;
+        let history = session.messages;
+        if (existingMessageId) {
+            const existingIndex = session.messages.findIndex((message) => message.id === existingMessageId && message.role === "user");
+            if (existingIndex < 0) {
+                res.status(400).json({ error: "Existing user message not found." });
+                return;
+            }
+            history = session.messages.slice(0, existingIndex);
+        }
+        else {
+            await store.addMessage(session.id, { role: "user", content: userMessage, source: "manual" });
+        }
+        res.writeHead(200, {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache, no-transform",
+            Connection: "keep-alive"
+        });
+        let assistantContent = "";
+        const toolMessages = [];
+        const workspaceSkills = await scanWorkspaceSkills(config.workspaceRoot);
+        const skillTriggers = selectSkillTriggers(workspaceSkills, `${manualContext}\n${userMessage}`);
+        const loadedSkillFiles = await loadTriggeredSkillFiles(config.workspaceRoot, skillTriggers);
+        const instructionFiles = req.body?.includeInstructionFiles ? await findInstructionFiles(config.workspaceRoot) : [];
+        if (skillTriggers.length) {
+            const skillTrace = skillTriggers
+                .map((trigger) => `- \`${trigger.skill.name}\` - ${trigger.confidence}; ${trigger.disclosure}; ${trigger.reason}`)
+                .join("\n");
+            await store.addMessage(session.id, {
+                role: "system",
+                content: `Workspace skill routing:\n\n${skillTrace}`,
+                source: "system"
+            });
+            res.write(`data: ${JSON.stringify({
+                type: "skills",
+                skills: skillTriggers.map((trigger) => trigger.skill),
+                triggers: skillTriggers,
+                loadedSkills: loadedSkillFiles.map(({ path, bytes }) => ({ path, bytes }))
+            })}\n\n`);
+        }
+        const contextPacket = buildContextPacket({
+            reviewPrompt,
+            manualContext,
+            files: session.files,
+            instructionFiles,
+            workspaceSkills,
+            skillTriggers,
+            loadedSkillFiles,
+            history,
+            userMessage
+        });
+        await streamOpenAIReview({
+            apiKey,
+            baseURL: config.openaiBaseURL,
+            apiMode,
+            model,
+            contextPacket,
+            workspaceRoot: config.workspaceRoot,
+            allowedWriteExtensions: config.allowedWriteExtensions,
+            enableTools: Boolean(req.body?.enableTools) && apiMode === "chat",
+            signal: abortController.signal,
+            onToolCall(name, args) {
+                toolMessages.push({
+                    name,
+                    content: `Calling \`${name}\` with:\n\n\`\`\`json\n${args}\n\`\`\``
+                });
+                res.write(`data: ${JSON.stringify({ type: "tool_call", name, args })}\n\n`);
+            },
+            onToolResult(name, result) {
+                toolMessages.push({
+                    name,
+                    content: `Result from \`${name}\`:\n\n\`\`\`\n${String(result).slice(0, 4000)}\n\`\`\``
+                });
+                res.write(`data: ${JSON.stringify({ type: "tool_result", name, result })}\n\n`);
+            },
+            onDelta(delta) {
+                assistantContent += delta;
+                res.write(`data: ${JSON.stringify({ type: "delta", delta })}\n\n`);
+            }
+        });
+        for (const toolMessage of toolMessages) {
+            await store.addMessage(session.id, {
+                role: "tool",
+                content: toolMessage.content,
+                source: "model",
+                toolName: toolMessage.name
+            });
+        }
+        if (assistantContent.trim()) {
+            await store.addMessage(session.id, {
+                role: "assistant",
+                content: assistantContent,
+                source: "model",
+                model,
+                apiMode
+            });
+        }
+        res.write(`data: ${JSON.stringify({ type: "done" })}\n\n`);
+        res.end();
+    }
+    catch (error) {
+        if (!res.headersSent) {
+            next(error);
+            return;
+        }
+        res.write(`data: ${JSON.stringify({ type: "error", error: errorMessage(error) })}\n\n`);
+        res.end();
+    }
+});
+app.use(express.static(clientDist));
+app.get("*path", (_req, res) => {
+    res.sendFile(resolve(clientDist, "index.html"));
+});
+app.use((error, _req, res, _next) => {
+    res.status(400).json({ error: errorMessage(error) });
+});
+app.listen(config.port, () => {
+    console.log(`Research Sidecar: http://localhost:${config.port}`);
+    console.log(`Workspace root: ${config.workspaceRoot}`);
+});
+function errorMessage(error) {
+    return error instanceof Error ? error.message : "Unknown error.";
+}
+function publicConfig() {
+    return {
+        workspaceRoot: config.workspaceRoot,
+        graphManifestPath: config.graphManifestPath,
+        defaultModel: config.defaultModel,
+        openaiBaseURL: config.openaiBaseURL || null,
+        apiMode: config.apiMode,
+        hasOpenAIKey: Boolean(config.openaiAPIKey)
+    };
+}

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@binarycheater/research-sidecar",
+  "version": "0.1.0",
+  "description": "Local research graph sidecar and CLI for Codex-assisted research workflows.",
+  "keywords": [
+    "research",
+    "codex",
+    "graph",
+    "markdown",
+    "sidecar",
+    "workspace",
+    "skills"
+  ],
+  "homepage": "https://github.com/BinaryCheater/scholar-mode#readme",
+  "bugs": {
+    "url": "https://github.com/BinaryCheater/scholar-mode/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BinaryCheater/scholar-mode.git",
+    "directory": "sidecar"
+  },
+  "license": "MIT",
+  "author": "BinaryCheater",
+  "engines": {
+    "node": ">=20"
+  },
+  "private": false,
+  "type": "module",
+  "bin": {
+    "research-sidecar": "bin/research-sidecar.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "dist-server",
+    "!dist-server/**/*.tsbuildinfo",
+    "scripts",
+    "skills",
+    "package.json",
+    "LICENSE",
+    "README.md",
+    "README.zh.md"
+  ],
+  "scripts": {
+    "dev": "tsx src/server/index.ts",
+    "build": "vite build && tsc -p tsconfig.server.json",
+    "prepack": "npm run build && node scripts/prepare-package.mjs",
+    "start": "node dist-server/server/index.js",
+    "codex:install": "node scripts/codex-sidecar.mjs install",
+    "codex:ask": "node scripts/codex-sidecar.mjs ask",
+    "codex:call": "node scripts/codex-sidecar.mjs call",
+    "codex:session": "node scripts/codex-sidecar.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@vitejs/plugin-react": "^5.1.1",
+    "@xyflow/react": "^12.10.2",
+    "express": "^5.2.1",
+    "katex": "^0.16.46",
+    "openai": "^6.10.0",
+    "react": "^19.2.1",
+    "react-dom": "^19.2.1",
+    "react-markdown": "^10.1.0",
+    "rehype-katex": "^7.0.1",
+    "remark-gfm": "^4.0.1",
+    "remark-math": "^6.0.0",
+    "vite": "^7.2.7",
+    "yaml": "^2.9.0",
+    "zod": "^4.2.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.0.0",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
+  }
+}