slidev-addon-agent 0.0.1

package/dist/app/index.js

@@ -0,0 +1,101 @@
+import path from "node:path";
+import { readFile, stat } from "node:fs/promises";
+import { Hono } from "hono";
+import { env } from "../lib/env.js";
+function resolveRootDir() {
+    return path.resolve(env(process.env, "SLIDEV_AGENT_ROOT_DIR") || process.cwd());
+}
+function normalizeBasePath(basePath) {
+    if (!basePath.startsWith("/"))
+        return `/${basePath}`;
+    return basePath.replace(/\/+$/, "");
+}
+function getMimeType(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+    switch (extension) {
+        case ".html":
+            return "text/html; charset=utf-8";
+        case ".js":
+            return "application/javascript; charset=utf-8";
+        case ".mjs":
+            return "application/javascript; charset=utf-8";
+        case ".css":
+            return "text/css; charset=utf-8";
+        case ".json":
+            return "application/json; charset=utf-8";
+        case ".svg":
+            return "image/svg+xml";
+        case ".png":
+            return "image/png";
+        case ".jpg":
+        case ".jpeg":
+            return "image/jpeg";
+        case ".gif":
+            return "image/gif";
+        case ".webp":
+            return "image/webp";
+        case ".woff":
+            return "font/woff";
+        case ".woff2":
+            return "font/woff2";
+        default:
+            return "application/octet-stream";
+    }
+}
+async function exists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function proxyToDevServer(requestUrl, assetPath) {
+    const devServerUrl = new URL(env(process.env, "SLIDEV_AGENT_DEV_URL", "http://localhost:3030"));
+    const targetUrl = new URL(assetPath || "/", devServerUrl);
+    targetUrl.search = requestUrl.search;
+    const response = await fetch(targetUrl);
+    const body = await response.arrayBuffer();
+    return new Response(body, {
+        status: response.status,
+        headers: response.headers,
+    });
+}
+const app = new Hono();
+const basePath = normalizeBasePath(env(process.env, "SLIDEV_AGENT_APP_BASE_PATH", "/slidev-agent"));
+app.get("/", c => c.redirect(`${basePath}/`, 302));
+app.get(basePath, c => c.redirect(`${basePath}/`, 302));
+app.get(`${basePath}/*`, async (c) => {
+    const requestUrl = new URL(c.req.url);
+    const assetPath = requestUrl.pathname.slice(basePath.length) || "/";
+    const distRoot = path.join(resolveRootDir(), "dist");
+    if (await exists(path.join(distRoot, "index.html"))) {
+        const candidatePath = path.normalize(path.join(distRoot, assetPath));
+        const safeRoot = `${distRoot}${path.sep}`;
+        const safeCandidate = candidatePath === distRoot || candidatePath.startsWith(safeRoot);
+        if (!safeCandidate)
+            return c.text("Invalid asset path", 400);
+        const isSpaRoute = !path.extname(assetPath);
+        const filePath = await exists(candidatePath)
+            ? candidatePath
+            : isSpaRoute
+                ? path.join(distRoot, "index.html")
+                : "";
+        if (!filePath)
+            return c.text("Asset not found", 404);
+        const content = await readFile(filePath);
+        return new Response(content, {
+            headers: {
+                "content-type": getMimeType(filePath),
+            },
+        });
+    }
+    try {
+        return await proxyToDevServer(requestUrl, assetPath);
+    }
+    catch {
+        return c.text(`Slidev app is not available yet. Start \`slidev-agent dev\` or build the deck so LangGraph can serve it from ${basePath}/.`, 503);
+    }
+});
+export { app };

package/dist/bin/slidev-agent.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { writeLanggraphJsonIfMissing } from "../lib/langgraph-init.js";
+import { pullRemoteSlides, pushRemoteSlides, resolveSlideEntry } from "../lib/bridge.js";
+const [, , command = "dev", ...rest] = process.argv;
+const require = createRequire(import.meta.url);
+function getNpxCommand() {
+    return process.platform === "win32" ? "npx.cmd" : "npx";
+}
+function spawnCommand(commandName, args, options = {}) {
+    return spawn(commandName, args, {
+        cwd: process.cwd(),
+        stdio: "inherit",
+        ...options,
+    });
+}
+function resolvePackageBin(packageName, preferredBinName) {
+    const packageJsonPath = require.resolve(`${packageName}/package.json`);
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    const packageRoot = path.dirname(packageJsonPath);
+    if (typeof packageJson.bin === "string")
+        return path.resolve(packageRoot, packageJson.bin);
+    if (packageJson.bin && typeof packageJson.bin === "object") {
+        const selectedBin = preferredBinName
+            ? packageJson.bin[preferredBinName]
+            : Object.values(packageJson.bin)[0];
+        if (typeof selectedBin === "string")
+            return path.resolve(packageRoot, selectedBin);
+    }
+    throw new Error(`Could not resolve a binary for ${packageName}`);
+}
+async function fileExists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function ensureLanggraphJsonForDev(cwd) {
+    if (process.env.SLIDEV_AGENT_DISABLE_LANGGRAPH === "1")
+        return;
+    try {
+        writeLanggraphJsonIfMissing(cwd);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        console.warn(`slidev-agent: could not create langgraph.json (${msg}). LangGraph dev will not start.`);
+    }
+}
+async function startLangGraphDev() {
+    if (process.env.SLIDEV_AGENT_DISABLE_LANGGRAPH === "1")
+        return null;
+    const configPath = path.join(process.cwd(), "langgraph.json");
+    if (!await fileExists(configPath))
+        return null;
+    const langgraphBin = resolvePackageBin("@langchain/langgraph-cli", "langgraphjs");
+    return spawnCommand(process.execPath, [
+        langgraphBin,
+        "dev",
+        "--config",
+        "langgraph.json",
+        "--no-browser",
+    ]);
+}
+/** Resolves when `child` has exited (immediately if it already has). */
+function onceChildExit(child) {
+    return new Promise((resolve) => {
+        if (child.exitCode !== null || child.signalCode !== null) {
+            resolve();
+            return;
+        }
+        child.once("exit", () => resolve());
+    });
+}
+const CHILD_SHUTDOWN_TIMEOUT_MS = 10_000;
+async function waitForChildrenThenExit(slidevChild, langgraphChild, exitCode) {
+    const waitFor = [onceChildExit(slidevChild)];
+    if (langgraphChild)
+        waitFor.push(onceChildExit(langgraphChild));
+    const timeout = setTimeout(() => {
+        langgraphChild?.kill("SIGKILL");
+        slidevChild.kill("SIGKILL");
+    }, CHILD_SHUTDOWN_TIMEOUT_MS);
+    try {
+        await Promise.all(waitFor);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+    process.exit(exitCode);
+}
+async function run() {
+    if (command === "sync") {
+        const subcommand = rest[0] || "pull";
+        if (subcommand === "pull") {
+            const result = await pullRemoteSlides(process.cwd());
+            if (result.mode === "local")
+                console.log(`No remote bridge configured, using local entry at ${result.entry}`);
+            else
+                console.log(`Pulled ${result.manifest.files.length} files into ${result.manifest.generatedRoot}`);
+            return;
+        }
+        if (subcommand === "push") {
+            await pushRemoteSlides(process.cwd());
+            console.log("Pushed generated slides back to the bridge.");
+            return;
+        }
+        throw new Error(`Unknown sync subcommand: ${subcommand}`);
+    }
+    const { entry } = await resolveSlideEntry(process.cwd());
+    const slidevArgs = command === "dev"
+        ? [entry, ...rest]
+        : [command, entry, ...rest];
+    if (command === "dev")
+        ensureLanggraphJsonForDev(process.cwd());
+    const langgraphChild = command === "dev" ? await startLangGraphDev() : null;
+    const slidevChild = spawnCommand(getNpxCommand(), ["slidev", ...slidevArgs]);
+    let isShuttingDown = false;
+    function shutdown(exitCode = 0) {
+        if (isShuttingDown) {
+            // Second Ctrl+C (or SIGTERM) while waiting for children: force quit.
+            langgraphChild?.kill("SIGKILL");
+            slidevChild.kill("SIGKILL");
+            process.exit(exitCode);
+            return;
+        }
+        isShuttingDown = true;
+        langgraphChild?.kill("SIGTERM");
+        slidevChild.kill("SIGTERM");
+        void waitForChildrenThenExit(slidevChild, langgraphChild, exitCode);
+    }
+    process.on("SIGINT", () => shutdown(0));
+    process.on("SIGTERM", () => shutdown(0));
+    langgraphChild?.on("exit", (code) => {
+        if (isShuttingDown)
+            return;
+        if ((code ?? 0) !== 0)
+            shutdown(code ?? 1);
+    });
+    slidevChild.on("exit", (code) => {
+        if (isShuttingDown)
+            return;
+        shutdown(code ?? 1);
+    });
+}
+run().catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/dist/lib/bridge.js

@@ -0,0 +1,151 @@
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { env } from "./env.js";
+const GENERATED_ROOT = ".slidev-agent/generated";
+const MANIFEST_PATH = ".slidev-agent/manifest.json";
+function resolveBridgeConfig(cwd) {
+    return {
+        entry: env(process.env, "SLIDEV_AGENT_ENTRY", "slides.md"),
+        routePrefix: env(process.env, "SLIDEV_AGENT_ROUTE_PREFIX", "/slidev-agent"),
+        cwd,
+    };
+}
+function isRemoteBridgeEnabled(config) {
+    return Boolean(config.apiUrl && config.deckId);
+}
+function normalizeRoutePrefix(routePrefix) {
+    if (!routePrefix.startsWith("/"))
+        return `/${routePrefix}`;
+    return routePrefix.replace(/\/$/, "");
+}
+function createDeckUrl(config) {
+    if (!config.apiUrl || !config.deckId)
+        return undefined;
+    const prefix = normalizeRoutePrefix(config.routePrefix);
+    const url = new URL(`${prefix}/decks/${encodeURIComponent(config.deckId)}`, config.apiUrl);
+    if (config.namespace)
+        url.searchParams.set("namespace", config.namespace);
+    return url;
+}
+function normalizePayload(payload, fallbackEntry) {
+    const entry = typeof payload.entry === "string" && payload.entry
+        ? payload.entry
+        : fallbackEntry;
+    if (Array.isArray(payload.files)) {
+        return {
+            entry,
+            files: payload.files.map((file) => ({
+                path: file.path,
+                content: file.content,
+            })),
+        };
+    }
+    if (payload.slides && typeof payload.slides === "object") {
+        return {
+            entry,
+            files: Object.entries(payload.slides).map(([filePath, content]) => ({
+                path: filePath,
+                content: String(content),
+            })),
+        };
+    }
+    throw new Error("Unsupported response shape. Expected `files` or `slides` in the bridge response.");
+}
+async function ensureParentDirectory(targetFile) {
+    await mkdir(path.dirname(targetFile), { recursive: true });
+}
+async function writeManifest(cwd, manifest) {
+    const manifestFile = path.join(cwd, MANIFEST_PATH);
+    await ensureParentDirectory(manifestFile);
+    await writeFile(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+async function readManifest(cwd) {
+    const manifestFile = path.join(cwd, MANIFEST_PATH);
+    const content = await readFile(manifestFile, "utf8");
+    return JSON.parse(content);
+}
+export async function pullRemoteSlides(cwd = process.cwd()) {
+    const config = resolveBridgeConfig(cwd);
+    if (!isRemoteBridgeEnabled(config)) {
+        return {
+            mode: "local",
+            entry: path.join(cwd, config.entry),
+            manifest: null,
+        };
+    }
+    const deckUrl = createDeckUrl(config);
+    if (!deckUrl) {
+        throw new Error("Remote sync is not configured. Set SLIDEV_AGENT_API_URL and SLIDEV_AGENT_DECK_ID.");
+    }
+    const response = await fetch(deckUrl, {
+        headers: {
+            accept: "application/json",
+        },
+    });
+    if (!response.ok)
+        throw new Error(`Bridge pull failed with ${response.status} ${response.statusText}`);
+    const payload = normalizePayload(await response.json(), config.entry);
+    const generatedRoot = path.join(cwd, GENERATED_ROOT);
+    await rm(generatedRoot, { recursive: true, force: true });
+    await mkdir(generatedRoot, { recursive: true });
+    for (const file of payload.files) {
+        const outputFile = path.join(generatedRoot, file.path);
+        await ensureParentDirectory(outputFile);
+        await writeFile(outputFile, file.content, "utf8");
+    }
+    const manifest = {
+        entry: payload.entry,
+        generatedRoot: GENERATED_ROOT,
+        files: payload.files.map(file => file.path),
+    };
+    await writeManifest(cwd, manifest);
+    return {
+        mode: "remote",
+        entry: path.join(generatedRoot, payload.entry),
+        manifest,
+    };
+}
+export async function pushRemoteSlides(cwd = process.cwd()) {
+    const config = resolveBridgeConfig(cwd);
+    if (!isRemoteBridgeEnabled(config))
+        throw new Error("Remote sync is not configured. Set SLIDEV_AGENT_API_URL and SLIDEV_AGENT_DECK_ID.");
+    const manifest = await readManifest(cwd);
+    const generatedRoot = path.join(cwd, manifest.generatedRoot);
+    const files = [];
+    for (const filePath of manifest.files) {
+        const absoluteFile = path.join(generatedRoot, filePath);
+        files.push({
+            path: filePath,
+            content: await readFile(absoluteFile, "utf8"),
+        });
+    }
+    const deckUrl = createDeckUrl(config);
+    if (!deckUrl) {
+        throw new Error("Remote sync is not configured. Set SLIDEV_AGENT_API_URL and SLIDEV_AGENT_DECK_ID.");
+    }
+    const response = await fetch(deckUrl, {
+        method: "PUT",
+        headers: {
+            "content-type": "application/json",
+            accept: "application/json",
+        },
+        body: JSON.stringify({
+            entry: manifest.entry,
+            files,
+        }),
+    });
+    if (!response.ok)
+        throw new Error(`Bridge push failed with ${response.status} ${response.statusText}`);
+}
+export async function resolveSlideEntry(cwd = process.cwd()) {
+    const config = resolveBridgeConfig(cwd);
+    if (isRemoteBridgeEnabled(config))
+        return pullRemoteSlides(cwd);
+    const entryFile = path.join(cwd, config.entry);
+    await stat(entryFile);
+    return {
+        mode: "local",
+        entry: entryFile,
+        manifest: null,
+    };
+}

package/dist/lib/env.js

@@ -0,0 +1,17 @@
+export function env(source, name, fallback) {
+    const value = source[name];
+    return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}
+const globalEnv = "process" in globalThis
+    ? globalThis.process.env
+    : import.meta.env ?? {};
+const anthropicEnv = env(globalEnv, "ANTHROPIC_API_KEY");
+const googleEnv = env(globalEnv, "GOOGLE_API_KEY");
+const openaiEnv = env(globalEnv, "OPENAI_API_KEY");
+export const model = env(globalEnv, "SLIDEV_AGENT_MODEL") ?? (anthropicEnv
+    ? "anthropic:claude-sonnet-4-6"
+    : googleEnv
+        ? "google:gemini-2.5-flash"
+        : openaiEnv
+            ? "openai:gpt-5.4"
+            : undefined);

package/dist/lib/headless-tools.js

@@ -0,0 +1,10 @@
+import { tool } from "langchain";
+import { z } from "zod";
+export const slidevGoToSlide = tool({
+    name: "slidev_go_to_slide",
+    description: "Navigate the active Slidev presentation in the user's browser to a specific 1-based slide number. Use this after creating a new slide when you know its final index.",
+    schema: z.object({
+        page: z.number().int().positive().describe("The 1-based Slidev page number to open."),
+        reason: z.string().optional().describe("Optional short explanation for the navigation."),
+    }),
+});

package/dist/lib/langgraph-init.js

@@ -0,0 +1,59 @@
+import { existsSync } from "node:fs";
+import { writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+function posixRelativeToCwd(cwd, absoluteFile) {
+    const rel = path.relative(cwd, absoluteFile).replace(/\\/g, "/");
+    if (!rel)
+        return ".";
+    return rel.startsWith(".") ? rel : `./${rel}`;
+}
+/**
+ * Resolves installed `slidev-addon-agent` entry files and returns graph spec strings
+ * for langgraph.json (path + export name).
+ */
+export function resolveSlidevAddonGraphSpecs(cwd) {
+    const packageJsonPath = path.join(cwd, "package.json");
+    if (!existsSync(packageJsonPath)) {
+        throw new Error(`No package.json in ${cwd}. Run slidev-agent dev from your Slidev project root (where package.json lives).`);
+    }
+    const require = createRequire(packageJsonPath);
+    let pkgRoot;
+    try {
+        pkgRoot = path.dirname(require.resolve("slidev-addon-agent"));
+    }
+    catch {
+        throw new Error("Could not resolve \"slidev-addon-agent\". Install it in this project, e.g. pnpm add slidev-addon-agent");
+    }
+    const agentFile = path.join(pkgRoot, "agent", "index.ts");
+    const appFile = path.join(pkgRoot, "app", "index.ts");
+    return {
+        agent: `${posixRelativeToCwd(cwd, agentFile)}:agent`,
+        app: `${posixRelativeToCwd(cwd, appFile)}:app`,
+    };
+}
+export function buildLanggraphJson(cwd) {
+    const { agent, app } = resolveSlidevAddonGraphSpecs(cwd);
+    return {
+        node_version: "20",
+        dependencies: ["."],
+        graphs: {
+            agent,
+        },
+        http: {
+            app,
+        },
+        env: ".env",
+    };
+}
+/**
+ * Writes `langgraph.json` when it is missing (first `slidev-agent dev`).
+ * Does not overwrite an existing file.
+ */
+export function writeLanggraphJsonIfMissing(cwd) {
+    const outPath = path.join(cwd, "langgraph.json");
+    if (existsSync(outPath))
+        return;
+    const config = buildLanggraphJson(cwd);
+    writeFileSync(outPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}

package/dist/lib/review-tool.js

@@ -0,0 +1,98 @@
+import path from "node:path";
+import { readFile, stat } from "node:fs/promises";
+import { initChatModel, tool } from "langchain";
+import { z } from "zod";
+import { readTrimmedEnv } from "./env.js";
+const slidevReviewScreenshotSchema = z.object({
+    imagePath: z.string().min(1).describe("Path to the exported screenshot image. Relative to the project root or an absolute path within it."),
+    slideIndex: z.number().int().positive().optional().describe("Optional 1-based slide index represented by the screenshot."),
+    focus: z.string().optional().describe("Optional short note about what to scrutinize most closely."),
+});
+const slidevReviewScreenshotResultSchema = z.object({
+    pass: z.boolean().describe("Whether the slide looks presentation-ready in the screenshot."),
+    summary: z.string().describe("Short visual verdict."),
+    issues: z.array(z.string()).describe("Concrete visual problems found in the screenshot."),
+    suggestions: z.array(z.string()).describe("Targeted improvements to address the issues."),
+});
+const supportedImageMimeTypes = {
+    ".gif": "image/gif",
+    ".jpeg": "image/jpeg",
+    ".jpg": "image/jpeg",
+    ".png": "image/png",
+    ".webp": "image/webp",
+};
+function resolveImagePath(rootDir, imagePath) {
+    const absoluteRoot = path.resolve(rootDir);
+    const resolved = path.isAbsolute(imagePath)
+        ? path.resolve(imagePath)
+        : path.resolve(absoluteRoot, imagePath);
+    if (resolved === absoluteRoot)
+        throw new Error("Screenshot path must point to an image file, not the project root.");
+    if (!resolved.startsWith(`${absoluteRoot}${path.sep}`))
+        throw new Error("Screenshot path must stay within the project root.");
+    return resolved;
+}
+function getImageMimeType(filePath) {
+    return supportedImageMimeTypes[path.extname(filePath).toLowerCase()] || "";
+}
+export function createSlidevReviewScreenshotTool(options) {
+    const rootDir = path.resolve(options.rootDir);
+    const reviewModelName = readTrimmedEnv(process.env, "SLIDEV_AGENT_REVIEW_MODEL")
+        || options.model
+        || readTrimmedEnv(process.env, "SLIDEV_AGENT_MODEL");
+    let reviewModelPromise = null;
+    async function getReviewModel() {
+        if (!reviewModelName) {
+            throw new Error("No screenshot review model is configured. Set `SLIDEV_AGENT_MODEL` or `SLIDEV_AGENT_REVIEW_MODEL` to a vision-capable chat model.");
+        }
+        reviewModelPromise ??= initChatModel(reviewModelName, {
+            temperature: 0,
+        });
+        return reviewModelPromise;
+    }
+    return tool(async ({ imagePath, slideIndex, focus }) => {
+        const resolvedImagePath = resolveImagePath(rootDir, imagePath);
+        const fileInfo = await stat(resolvedImagePath).catch(() => null);
+        if (!fileInfo?.isFile())
+            throw new Error(`Screenshot not found: ${imagePath}`);
+        const mimeType = getImageMimeType(resolvedImagePath);
+        if (!mimeType)
+            throw new Error(`Unsupported screenshot format for review: ${path.extname(resolvedImagePath) || "unknown"}`);
+        const imageData = await readFile(resolvedImagePath, "base64");
+        const reviewModel = await getReviewModel();
+        const structuredReviewer = reviewModel.withStructuredOutput(slidevReviewScreenshotResultSchema);
+        const review = await structuredReviewer.invoke([
+            {
+                role: "user",
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `Review this rendered Slidev slide screenshot${slideIndex ? ` for slide ${slideIndex}` : ""}.`,
+                            "Judge only what is visible in the image. Do not guess about hidden or source markdown content.",
+                            "Mark the slide as failing if you notice clipped or off-screen content, overflow, cramped layout, collisions, unreadable or tiny text, broken wrapping, poor contrast, or obvious alignment problems.",
+                            "Only pass the slide if it looks presentation-ready.",
+                            focus ? `Pay extra attention to: ${focus}` : "",
+                            "Return concise structured output.",
+                        ].filter(Boolean).join("\n"),
+                    },
+                    {
+                        type: "image",
+                        source_type: "base64",
+                        data: imageData,
+                        mimeType,
+                    },
+                ],
+            },
+        ]);
+        return {
+            ...review,
+            imagePath: path.relative(rootDir, resolvedImagePath) || path.basename(resolvedImagePath),
+            slideIndex: slideIndex || null,
+        };
+    }, {
+        name: "slidev_review_screenshot",
+        description: "Review an exported slide screenshot with a multimodal model and report visual issues such as clipping, overflow, collisions, poor contrast, and unreadable text.",
+        schema: slidevReviewScreenshotSchema,
+    });
+}