@binarycheater/research-sidecar 0.1.0

package/dist-server/lib/workspaceInstall.js

@@ -0,0 +1,157 @@
+import { access, cp, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const DEFAULT_ALLOWED_WRITE_EXTENSIONS = [".md", ".markdown", ".html", ".htm", ".yaml", ".yml"];
+export async function installWorkspaceScaffold(workspaceRoot, options = {}) {
+    const root = resolve(workspaceRoot);
+    const graphManifestPath = normalizeWorkspacePath(options.graphManifestPath || "research/graph.yaml");
+    const sideDir = join(root, ".side");
+    const sessionsDir = join(sideDir, "sessions");
+    await mkdir(root, { recursive: true });
+    await mkdir(sessionsDir, { recursive: true });
+    await writeSidecarConfig(join(sideDir, "config.json"), graphManifestPath);
+    await writeFileIfMissing(join(sessionsDir, "index.json"), `${JSON.stringify({ sessions: [] }, null, 2)}\n`);
+    await ensureGitignore(root);
+    const skills = options.installSkills === false ? undefined : await installBundledSkills(root, { force: options.force });
+    if (options.createGraph !== false) {
+        await installStarterGraph(root, graphManifestPath, Boolean(options.force));
+    }
+    return {
+        workspaceRoot: root,
+        configPath: join(sideDir, "config.json"),
+        graphManifestPath,
+        skills
+    };
+}
+export async function installBundledSkills(workspaceRoot, options = {}) {
+    const sourceRoot = await findBundledSkillsRoot();
+    if (!sourceRoot)
+        return { sourceRoot: null, installed: [], skipped: [] };
+    const entries = await readdir(sourceRoot, { withFileTypes: true });
+    const targetRoot = join(resolve(workspaceRoot), "skills");
+    const installed = [];
+    const skipped = [];
+    await mkdir(targetRoot, { recursive: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const source = join(sourceRoot, entry.name);
+        const target = join(targetRoot, entry.name);
+        if (!options.force && (await exists(target))) {
+            skipped.push(entry.name);
+            continue;
+        }
+        await cp(source, target, { recursive: true, force: true });
+        installed.push(entry.name);
+    }
+    return { sourceRoot, installed, skipped };
+}
+async function findBundledSkillsRoot() {
+    const moduleDir = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        resolve(moduleDir, "../../skills"),
+        resolve(moduleDir, "../../../skills"),
+        resolve(process.cwd(), "skills")
+    ];
+    for (const candidate of candidates) {
+        if (await exists(candidate))
+            return candidate;
+    }
+    return null;
+}
+async function writeSidecarConfig(configPath, graphManifestPath) {
+    const existing = await readJsonFile(configPath);
+    const config = {
+        ...existing,
+        graph: {
+            ...(existing.graph || {}),
+            manifestPath: graphManifestPath
+        },
+        tools: {
+            allowedWriteExtensions: DEFAULT_ALLOWED_WRITE_EXTENSIONS,
+            ...(existing.tools || {})
+        }
+    };
+    await mkdir(dirname(configPath), { recursive: true });
+    await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+async function installStarterGraph(workspaceRoot, graphManifestPath, force) {
+    const graphPath = join(workspaceRoot, graphManifestPath);
+    const graphDir = dirname(graphPath);
+    const notePath = join(graphDir, "rq.main.md");
+    const graphBody = `root: rq.main
+
+ui:
+  layout: LR
+  expanded: [rq.main]
+
+nodes:
+  - id: rq.main
+    title: Core research question
+    type: question
+    file: ./rq.main.md
+    status: active
+    tags: [framing]
+
+edges: []
+`;
+    const noteBody = `# Core research question
+
+Use this note as the first graph node, or replace it with your existing research Markdown.
+`;
+    await mkdir(graphDir, { recursive: true });
+    await writeFileMaybe(graphPath, graphBody, force);
+    await writeFileMaybe(notePath, noteBody, force);
+}
+async function ensureGitignore(workspaceRoot) {
+    const path = join(workspaceRoot, ".gitignore");
+    const current = await readTextFile(path);
+    if (current === null) {
+        await writeFile(path, ".side/\n", "utf8");
+        return;
+    }
+    if (!current.split(/\r?\n/).some((line) => line.trim() === ".side/" || line.trim() === ".side")) {
+        const suffix = current.endsWith("\n") || current.length === 0 ? "" : "\n";
+        await writeFile(path, `${current}${suffix}.side/\n`, "utf8");
+    }
+}
+async function writeFileIfMissing(path, body) {
+    if (await exists(path))
+        return;
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, body, "utf8");
+}
+async function writeFileMaybe(path, body, force) {
+    if (!force && (await exists(path)))
+        return;
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, body, "utf8");
+}
+async function readJsonFile(path) {
+    const raw = await readTextFile(path);
+    if (!raw?.trim())
+        return {};
+    return JSON.parse(raw);
+}
+async function readTextFile(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeWorkspacePath(value) {
+    return value.trim().replace(/^\.\//, "").replace(/^\/+/, "");
+}

package/dist-server/lib/workspaceMeta.js

@@ -0,0 +1,171 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { readWorkspaceFile } from "./files.js";
+const SKIP_DIRS = new Set([".git", "node_modules", "dist", "dist-server", "data", ".tmp-tests"]);
+const INSTRUCTION_RE = /^(CLAUDE|AGENTS)\.md$/i;
+const STOPWORDS = new Set([
+    "the",
+    "and",
+    "for",
+    "with",
+    "from",
+    "this",
+    "that",
+    "use",
+    "using",
+    "when",
+    "task",
+    "asks",
+    "user",
+    "mode",
+    "skill",
+    "review",
+    "analysis",
+    "context"
+]);
+export async function findInstructionFiles(workspaceRoot) {
+    const files = await listFiles(workspaceRoot, 3);
+    const matches = files.filter((file) => INSTRUCTION_RE.test(file.split("/").pop() || "")).sort();
+    const snapshots = await Promise.all(matches.map((path) => readWorkspaceFile(workspaceRoot, path)));
+    return snapshots;
+}
+export async function scanWorkspaceSkills(workspaceRoot) {
+    const files = await listFiles(workspaceRoot, 5);
+    const skillFiles = files.filter((file) => file.endsWith("SKILL.md")).sort();
+    const skillsByName = new Map();
+    for (const path of skillFiles) {
+        const content = await readFile(join(workspaceRoot, path), "utf8");
+        const meta = parseSkillFrontmatter(content);
+        if (meta.name) {
+            const skill = {
+                name: meta.name,
+                description: meta.description || "",
+                path
+            };
+            const key = meta.name.toLowerCase();
+            const existing = skillsByName.get(key);
+            if (!existing || skillPriority(skill.path) > skillPriority(existing.path)) {
+                skillsByName.set(key, skill);
+            }
+        }
+    }
+    return [...skillsByName.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+export function selectTriggeredSkills(skills, text) {
+    return selectSkillTriggers(skills, text).map((trigger) => trigger.skill);
+}
+export function selectSkillTriggers(skills, text) {
+    const query = tokenize(text);
+    const rawText = text.toLowerCase();
+    if (!query.size && !rawText.trim())
+        return [];
+    return skills
+        .map((skill) => ({ skill, score: scoreSkill(skill, query, rawText) }))
+        .filter((item) => item.score >= 2)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 5)
+        .map(({ skill, score }) => {
+        const confidence = score >= 3 ? "high" : "medium";
+        return {
+            skill,
+            score,
+            confidence,
+            reason: triggerReason(skill, score, text),
+            disclosure: confidence === "high" ? "loaded" : "candidate"
+        };
+    });
+}
+export async function loadTriggeredSkillFiles(workspaceRoot, triggers) {
+    const loaded = triggers.filter((trigger) => trigger.disclosure === "loaded").slice(0, 3);
+    return Promise.all(loaded.map((trigger) => readWorkspaceFile(workspaceRoot, trigger.skill.path)));
+}
+export async function loadSkillByReference(workspaceRoot, reference) {
+    const normalized = reference.trim().toLowerCase();
+    if (!normalized) {
+        throw new Error("Skill name or path is required.");
+    }
+    const skills = await scanWorkspaceSkills(workspaceRoot);
+    const match = skills.find((skill) => skill.name.toLowerCase() === normalized ||
+        skill.path.toLowerCase() === normalized ||
+        skill.path.toLowerCase().endsWith(`/${normalized}`));
+    if (!match) {
+        throw new Error(`Skill not found: ${reference}`);
+    }
+    return readWorkspaceFile(workspaceRoot, match.path);
+}
+async function listFiles(root, maxDepth, dir = "", depth = 0) {
+    if (depth > maxDepth)
+        return [];
+    let entries;
+    try {
+        entries = await readdir(join(root, dir), { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const results = [];
+    for (const entry of entries) {
+        if (entry.name.startsWith(".") && entry.name !== ".agents")
+            continue;
+        if (SKIP_DIRS.has(entry.name))
+            continue;
+        const rel = dir ? `${dir}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            results.push(...(await listFiles(root, maxDepth, rel, depth + 1)));
+        }
+        else if (entry.isFile()) {
+            const info = await stat(join(root, rel));
+            if (info.size <= 512_000)
+                results.push(relative(root, join(root, rel)));
+        }
+    }
+    return results;
+}
+function parseSkillFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    const raw = match?.[1] || "";
+    return {
+        name: raw.match(/^name:\s*["']?(.+?)["']?\s*$/m)?.[1]?.trim(),
+        description: raw.match(/^description:\s*["']?([\s\S]*?)["']?\s*$/m)?.[1]?.trim()
+    };
+}
+function skillPriority(path) {
+    if (/^skills\/[^/]+\/SKILL\.md$/i.test(path))
+        return 3;
+    if (/^\.agents\/skills\/[^/]+\/SKILL\.md$/i.test(path))
+        return 2;
+    return 1;
+}
+function scoreSkill(skill, query, rawText) {
+    const normalizedName = skill.name.toLowerCase();
+    const spacedName = normalizedName.replace(/[-_]+/g, " ");
+    const haystack = tokenize(`${skill.name} ${spacedName} ${skill.description}`);
+    let score = 0;
+    for (const token of query) {
+        if (haystack.has(token))
+            score += 1;
+    }
+    if (rawText.includes(normalizedName) || rawText.includes(spacedName))
+        score += 6;
+    return score;
+}
+function triggerReason(skill, score, text) {
+    const rawText = text.toLowerCase();
+    const normalizedName = skill.name.toLowerCase();
+    const spacedName = normalizedName.replace(/[-_]+/g, " ");
+    if (rawText.includes(normalizedName) || rawText.includes(spacedName)) {
+        return `Prompt explicitly mentions ${skill.name}.`;
+    }
+    const query = tokenize(text);
+    const haystack = tokenize(`${skill.name} ${spacedName} ${skill.description}`);
+    const matches = [...query].filter((token) => haystack.has(token)).slice(0, 5);
+    return matches.length
+        ? `Matched skill description terms: ${matches.join(", ")}. Score ${score}.`
+        : `Matched skill routing score ${score}.`;
+}
+function tokenize(text) {
+    return new Set(text
+        .toLowerCase()
+        .split(/[^a-z0-9_\-\u4e00-\u9fff]+/u)
+        .filter((token) => (token.length > 2 || ["ai", "cv", "ml", "rl"].includes(token)) && !STOPWORDS.has(token)));
+}

package/dist-server/server/config.js

@@ -0,0 +1,82 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+const DEFAULT_ALLOWED_WRITE_EXTENSIONS = [".md", ".markdown", ".html", ".htm", ".yaml", ".yml"];
+const DEFAULT_GRAPH_MANIFEST_PATH = "research/graph.yaml";
+export function loadConfig(options = {}) {
+    const env = options.env || process.env;
+    const workspaceRoot = resolve(env.SIDECAR_WORKSPACE_ROOT || process.cwd());
+    const sideDir = resolve(workspaceRoot, ".side");
+    const configFile = resolve(sideDir, "config.json");
+    mkdirSync(sideDir, { recursive: true });
+    const persisted = readSidecarConfig(configFile);
+    const port = Number.parseInt(env.PORT || "4317", 10);
+    const openaiBaseURL = env.OPENAI_BASE_URL || persisted.openaiBaseURL;
+    const apiMode = persisted.apiMode || chooseApiMode(openaiBaseURL);
+    const allowedWriteExtensions = normalizeExtensions(persisted.tools?.allowedWriteExtensions);
+    const config = {
+        workspaceRoot,
+        sideDir,
+        dataFile: resolve(env.SIDECAR_DATA_FILE || resolve(sideDir, "sessions", "index.json")),
+        graphManifestPath: normalizeManifestPath(env.SIDECAR_GRAPH_MANIFEST || persisted.graph?.manifestPath),
+        defaultModel: env.SIDECAR_DEFAULT_MODEL || persisted.defaultModel || "gpt-5.5",
+        openaiAPIKey: env.OPENAI_API_KEY || persisted.openaiAPIKey,
+        openaiBaseURL,
+        apiMode,
+        port: Number.isFinite(port) ? port : 4317,
+        allowedWriteExtensions
+    };
+    writeSidecarConfig(configFile, config);
+    return config;
+}
+export function updateGraphManifestPath(config, manifestPath) {
+    const nextPath = normalizeManifestPath(manifestPath);
+    config.graphManifestPath = nextPath;
+    writeSidecarConfig(resolve(config.sideDir, "config.json"), config);
+    return config;
+}
+export function chooseApiMode(baseURL) {
+    if (!baseURL?.trim())
+        return "responses";
+    try {
+        const host = new URL(baseURL).hostname;
+        return host === "api.openai.com" || host.endsWith(".openai.com") ? "responses" : "chat";
+    }
+    catch {
+        return "chat";
+    }
+}
+function readSidecarConfig(path) {
+    if (!existsSync(path))
+        return {};
+    const raw = readFileSync(path, "utf8");
+    return raw.trim() ? JSON.parse(raw) : {};
+}
+function writeSidecarConfig(path, config) {
+    const body = {
+        defaultModel: config.defaultModel,
+        openaiAPIKey: config.openaiAPIKey,
+        openaiBaseURL: config.openaiBaseURL,
+        apiMode: config.apiMode,
+        graph: {
+            manifestPath: config.graphManifestPath
+        },
+        tools: {
+            allowedWriteExtensions: config.allowedWriteExtensions
+        }
+    };
+    writeFileSync(path, `${JSON.stringify(body, null, 2)}\n`);
+}
+function normalizeExtensions(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return DEFAULT_ALLOWED_WRITE_EXTENSIONS;
+    const normalized = value
+        .filter((item) => typeof item === "string" && item.trim().length > 0)
+        .map((item) => item.trim().toLowerCase())
+        .map((item) => (item.startsWith(".") ? item : `.${item}`));
+    return normalized.length ? Array.from(new Set(normalized)) : DEFAULT_ALLOWED_WRITE_EXTENSIONS;
+}
+function normalizeManifestPath(value) {
+    if (typeof value !== "string" || !value.trim())
+        return DEFAULT_GRAPH_MANIFEST_PATH;
+    return value.trim().replace(/^\.\//, "");
+}