ppt-template-reuse 0.4.0-rc.2

package/src/index.mjs

@@ -0,0 +1,2 @@
+export * from "./core/index.mjs";
+export { createMcpServer } from "./mcp/server.mjs";

package/src/install/installer.mjs

@@ -0,0 +1,293 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { exists, writeJsonAtomic } from "../core/io.mjs";
+import {
+  migrateLegacyCapsules,
+  resolveEngineHome,
+} from "../core/paths.mjs";
+
+const PACKAGE_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../..",
+);
+const SKILL_SOURCE = path.join(
+  PACKAGE_ROOT,
+  "skills",
+  "ppt-template-reuse",
+  "SKILL.md",
+);
+const SERVER_COMMAND =
+  process.platform === "win32"
+    ? "ppt-template-reuse-mcp.cmd"
+    : "ppt-template-reuse-mcp";
+
+function stripJsonComments(value) {
+  return value
+    .replace(/^\uFEFF/, "")
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/(^|[^:\\])\/\/.*$/gm, "$1")
+    .replace(/,\s*([}\]])/g, "$1");
+}
+
+async function readJsonc(candidate, fallback = {}) {
+  if (!(await exists(candidate))) return fallback;
+  return JSON.parse(stripJsonComments(await fs.readFile(candidate, "utf8")));
+}
+
+async function backup(candidate) {
+  if (!(await exists(candidate))) return null;
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const output = `${candidate}.backup-${stamp}`;
+  await fs.copyFile(candidate, output);
+  return output;
+}
+
+async function writeIfChanged(candidate, content, { dryRun = false } = {}) {
+  const prior = (await exists(candidate))
+    ? await fs.readFile(candidate, "utf8")
+    : null;
+  if (prior === content) return { path: candidate, changed: false, backup: null };
+  if (dryRun) return { path: candidate, changed: true, dryRun: true, backup: null };
+  await fs.mkdir(path.dirname(candidate), { recursive: true });
+  const saved = await backup(candidate);
+  const temporary = `${candidate}.${process.pid}.tmp`;
+  await fs.writeFile(temporary, content, "utf8");
+  await fs.rename(temporary, candidate);
+  return { path: candidate, changed: true, backup: saved };
+}
+
+async function mergeJsonConfig(candidate, mutator, options) {
+  const current = await readJsonc(candidate, {});
+  const next = structuredClone(current);
+  mutator(next);
+  return writeIfChanged(candidate, `${JSON.stringify(next, null, 2)}\n`, options);
+}
+
+async function mergeTomlMcp(candidate, options) {
+  const block = [
+    "[mcp_servers.ppt-template-reuse]",
+    `command = ${JSON.stringify(SERVER_COMMAND)}`,
+    "args = []",
+  ].join("\n");
+  const current = (await exists(candidate))
+    ? await fs.readFile(candidate, "utf8")
+    : "";
+  const pattern =
+    /(?:^|\n)\[mcp_servers\.ppt-template-reuse\][\s\S]*?(?=\n\[[^\]]+\]|\s*$)/;
+  const without = current.replace(pattern, "\n").trimEnd();
+  const next = `${without}${without ? "\n\n" : ""}${block}\n`;
+  return writeIfChanged(candidate, next, options);
+}
+
+async function copySkill(target, options) {
+  const source = await fs.readFile(SKILL_SOURCE, "utf8");
+  return writeIfChanged(target, source, options);
+}
+
+function hostCandidates(homeRoot) {
+  const kimiHome =
+    path.resolve(homeRoot) === path.resolve(os.homedir()) &&
+    process.env.KIMI_CODE_HOME
+      ? path.resolve(process.env.KIMI_CODE_HOME)
+      : path.join(homeRoot, ".kimi-code");
+  return {
+    codex: {
+      detected: [path.join(homeRoot, ".codex")],
+      skill: path.join(homeRoot, ".codex", "skills", "ppt-template-reuse", "SKILL.md"),
+      config: path.join(homeRoot, ".codex", "config.toml"),
+      configType: "toml",
+    },
+    claude: {
+      detected: [path.join(homeRoot, ".claude"), path.join(homeRoot, ".claude.json")],
+      skill: path.join(homeRoot, ".claude", "skills", "ppt-template-reuse", "SKILL.md"),
+      config: path.join(homeRoot, ".claude.json"),
+      configType: "json",
+    },
+    kimi: {
+      detected: [kimiHome],
+      skill: path.join(kimiHome, "skills", "ppt-template-reuse", "SKILL.md"),
+      config: path.join(kimiHome, "mcp.json"),
+      configType: "json",
+    },
+    workbuddy: {
+      detected: [path.join(homeRoot, ".workbuddy")],
+      skill: path.join(
+        resolveEngineHome(path.join(homeRoot, ".ppt-template-reuse")),
+        "imports",
+        "workbuddy",
+        "ppt-template-reuse",
+        "SKILL.md",
+      ),
+      config: path.join(
+        resolveEngineHome(path.join(homeRoot, ".ppt-template-reuse")),
+        "imports",
+        "workbuddy",
+        "mcp.json",
+      ),
+      configType: "json",
+      manualTrust: true,
+    },
+    "kimi-work": {
+      detected: [
+        path.join(
+          homeRoot,
+          "Library",
+          "Application Support",
+          "Kimi",
+        ),
+      ],
+      skill: path.join(
+        resolveEngineHome(path.join(homeRoot, ".ppt-template-reuse")),
+        "imports",
+        "kimi-work",
+        "ppt-template-reuse",
+        "SKILL.md",
+      ),
+      config: path.join(
+        resolveEngineHome(path.join(homeRoot, ".ppt-template-reuse")),
+        "imports",
+        "kimi-work",
+        "mcp.json",
+      ),
+      configType: "json",
+      manualTrust: true,
+    },
+  };
+}
+
+async function isDetected(record) {
+  for (const candidate of record.detected) {
+    if (await exists(candidate)) return true;
+  }
+  return false;
+}
+
+function mergeMcpJson(config) {
+  config.mcpServers ||= {};
+  config.mcpServers["ppt-template-reuse"] = {
+    command: SERVER_COMMAND,
+    args: [],
+  };
+}
+
+export async function installHosts({
+  host = "auto",
+  homeRoot = os.homedir(),
+  dryRun = false,
+} = {}) {
+  const legacyImport =
+    !dryRun && path.resolve(homeRoot) === path.resolve(os.homedir())
+      ? await migrateLegacyCapsules()
+      : {
+          imported: 0,
+          skipped: dryRun ? "dry-run" : "test-or-alternate-home",
+        };
+  const candidates = hostCandidates(path.resolve(homeRoot));
+  const requested =
+    host === "all"
+      ? Object.keys(candidates)
+      : host === "auto"
+        ? (
+            await Promise.all(
+              Object.entries(candidates).map(async ([name, value]) => [
+                name,
+                await isDetected(value),
+              ]),
+            )
+          )
+            .filter(([, detected]) => detected)
+            .map(([name]) => name)
+        : String(host)
+            .split(",")
+            .map((item) => item.trim().toLowerCase())
+            .filter(Boolean);
+  const unknown = requested.filter((name) => !candidates[name]);
+  if (unknown.length) throw new Error(`Unknown hosts: ${unknown.join(", ")}`);
+  const results = [];
+  for (const name of requested) {
+    const record = candidates[name];
+    const changes = [];
+    changes.push(await copySkill(record.skill, { dryRun }));
+    changes.push(
+      record.configType === "toml"
+        ? await mergeTomlMcp(record.config, { dryRun })
+        : await mergeJsonConfig(record.config, mergeMcpJson, { dryRun }),
+    );
+    results.push({
+      host: name,
+      detected: await isDetected(record),
+      manualTrustRequired: record.manualTrust === true,
+      changes,
+    });
+  }
+  return {
+    packageRoot: PACKAGE_ROOT,
+    serverCommand: SERVER_COMMAND,
+    homeRoot: path.resolve(homeRoot),
+    dryRun,
+    hosts: results,
+    actionRequired: results
+      .filter((item) => item.manualTrustRequired)
+      .map((item) => ({
+        host: item.host,
+        instruction:
+          "Import the prepared Skill folder and MCP JSON in the host UI, then approve the one-time local command trust prompt.",
+      })),
+    legacyImport,
+  };
+}
+
+export async function uninstallHost({
+  host,
+  homeRoot = os.homedir(),
+  dryRun = false,
+} = {}) {
+  const candidates = hostCandidates(path.resolve(homeRoot));
+  const record = candidates[host];
+  if (!record) throw new Error(`Unknown host: ${host}`);
+  const result = { host, removedSkill: false, configChanged: false, backups: [] };
+  if (await exists(record.skill)) {
+    if (!dryRun) {
+      const saved = await backup(record.skill);
+      if (saved) result.backups.push(saved);
+      await fs.unlink(record.skill);
+    }
+    result.removedSkill = true;
+  }
+  if (record.configType === "json") {
+    const config = await readJsonc(record.config, {});
+    if (config.mcpServers?.["ppt-template-reuse"]) {
+      delete config.mcpServers["ppt-template-reuse"];
+      if (!dryRun) {
+        const saved = await backup(record.config);
+        if (saved) result.backups.push(saved);
+        await writeJsonAtomic(record.config, config);
+      }
+      result.configChanged = true;
+    }
+  } else if (await exists(record.config)) {
+    const current = await fs.readFile(record.config, "utf8");
+    const next = current
+      .replace(
+        /(?:^|\n)\[mcp_servers\.ppt-template-reuse\][\s\S]*?(?=\n\[[^\]]+\]|\s*$)/,
+        "\n",
+      )
+      .trimEnd();
+    if (`${next}\n` !== current) {
+      if (!dryRun) {
+        const saved = await backup(record.config);
+        if (saved) result.backups.push(saved);
+        await fs.writeFile(record.config, `${next}\n`, "utf8");
+      }
+      result.configChanged = true;
+    }
+  }
+  return result;
+}
+
+export function installerPaths() {
+  return { packageRoot: PACKAGE_ROOT, skillSource: SKILL_SOURCE };
+}

package/src/mcp/server.mjs

@@ -0,0 +1,377 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import * as z from "zod/v4";
+
+import {
+  cancelSession,
+  createSession,
+  engineVersion,
+  getSessionStatus,
+  inspectSession,
+  planSession,
+  startGeneration,
+  submitSemantics,
+  supplyAssets,
+  validateSession,
+} from "../core/universal-engine.mjs";
+
+function textResult(value) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+    structuredContent: value,
+  };
+}
+
+function toolError(error) {
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(
+          {
+            error: {
+              code: error.code || "PPT_REUSE_ERROR",
+              message: error.message || String(error),
+              details: error.details,
+            },
+          },
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}
+
+function guarded(handler) {
+  return async (input) => {
+    try {
+      return textResult(await handler(input));
+    } catch (error) {
+      return toolError(error);
+    }
+  };
+}
+
+function resourceLinks(session) {
+  const links = [];
+  for (const [name, value] of Object.entries(session.artifacts || {})) {
+    if (Array.isArray(value)) {
+      value.forEach((_, index) =>
+        links.push({
+          type: "resource_link",
+          uri: `ppt://session/${session.id}/${name}/${index}`,
+          name: `${name}-${index + 1}`,
+        }),
+      );
+    } else if (typeof value === "string") {
+      links.push({
+        type: "resource_link",
+        uri: `ppt://session/${session.id}/${name}`,
+        name,
+      });
+    }
+  }
+  return links;
+}
+
+function statusResult(status) {
+  return {
+    content: [
+      { type: "text", text: JSON.stringify(status, null, 2) },
+      ...resourceLinks(status),
+    ],
+    structuredContent: status,
+  };
+}
+
+function registerTools(server, options = {}) {
+  const sessionIdSchema = {
+    sessionId: z.string().min(1).describe("Persistent PPT reuse session id"),
+  };
+  server.registerTool(
+    "ppt_create_session",
+    {
+      description:
+        "Register a PPTX/POTX template, source document, output path, allowed roots, and presentation requirements. This never uploads files.",
+      inputSchema: {
+        template: z.string(),
+        source: z.string(),
+        output: z.string(),
+        roots: z.array(z.string()).default([]),
+        requirements: z.record(z.string(), z.any()).default({}),
+      },
+    },
+    guarded((input) => createSession(input, options)),
+  );
+  server.registerTool(
+    "ppt_inspect",
+    {
+      description:
+        "Deterministically inspect template structure and source anchors, returning semantic packages the host AI must complete without deleting units.",
+      inputSchema: sessionIdSchema,
+    },
+    guarded(({ sessionId }) => inspectSession(sessionId, options)),
+  );
+  server.registerTool(
+    "ppt_submit_semantics",
+    {
+      description:
+        "Submit host-AI template and source semantics. Every extracted source id and anchor must be preserved exactly.",
+      inputSchema: {
+        ...sessionIdSchema,
+        templateProfile: z.record(z.string(), z.any()).optional(),
+        sourceSemantics: z.union([
+          z.array(z.record(z.string(), z.any())),
+          z.record(z.string(), z.any()),
+        ]),
+      },
+    },
+    guarded(({ sessionId, ...payload }) =>
+      submitSemantics(sessionId, payload, options),
+    ),
+  );
+  server.registerTool(
+    "ppt_plan",
+    {
+      description:
+        "Create and freeze an adaptive content plan, coverage audit, deterministic template-page sequence, and native edit map.",
+      inputSchema: {
+        ...sessionIdSchema,
+        density: z.string().optional(),
+        scope: z.string().optional(),
+        templateMode: z.string().optional(),
+        allowLowFit: z.boolean().default(false),
+        durationSeconds: z
+          .object({ min: z.number().optional(), max: z.number().optional() })
+          .optional(),
+      },
+    },
+    guarded(({ sessionId, ...planning }) =>
+      planSession(sessionId, planning, options),
+    ),
+  );
+  server.registerTool(
+    "ppt_supply_assets",
+    {
+      description:
+        "Register host-generated or user-supplied visual assets. Missing required visuals block generation instead of becoming gray placeholders.",
+      inputSchema: {
+        ...sessionIdSchema,
+        assets: z.array(
+          z.object({
+            sourceUnitId: z.string(),
+            type: z.string().default("image"),
+            path: z.string().optional(),
+            value: z.any().optional(),
+            alt: z.string().optional(),
+          }),
+        ),
+      },
+    },
+    guarded(({ sessionId, assets }) =>
+      supplyAssets(sessionId, assets, options),
+    ),
+  );
+  server.registerTool(
+    "ppt_generate",
+    {
+      description:
+        "Start native OOXML generation as a recoverable background job. Poll ppt_status for page events and previews.",
+      inputSchema: {
+        ...sessionIdSchema,
+        validate: z.boolean().default(true),
+        livePreview: z.boolean().default(true),
+      },
+    },
+    guarded(({ sessionId, validate, livePreview }) =>
+      Promise.resolve(
+        startGeneration(sessionId, { ...options, validate, livePreview }),
+      ),
+    ),
+  );
+  server.registerTool(
+    "ppt_status",
+    {
+      description:
+        "Read persistent status, warnings, action-required blocks, new page events, preview resources, and QA artifacts.",
+      inputSchema: {
+        ...sessionIdSchema,
+        afterEvent: z.number().int().min(0).default(0),
+      },
+    },
+    async ({ sessionId, afterEvent }) => {
+      try {
+        return statusResult(
+          await getSessionStatus(sessionId, { ...options, afterEvent }),
+        );
+      } catch (error) {
+        return toolError(error);
+      }
+    },
+  );
+  server.registerTool(
+    "ppt_validate",
+    {
+      description:
+        "Run structural, content, placeholder, notes, chart, page-count, LibreOffice rendering, rendered-text fidelity, and protected-region validation.",
+      inputSchema: sessionIdSchema,
+    },
+    guarded(({ sessionId }) => validateSession(sessionId, options)),
+  );
+  server.registerTool(
+    "ppt_cancel",
+    {
+      description:
+        "Safely mark a session cancelled while retaining its frozen plans and artifacts for later recovery.",
+      inputSchema: sessionIdSchema,
+    },
+    guarded(({ sessionId }) => cancelSession(sessionId, options)),
+  );
+}
+
+function mimeFor(candidate) {
+  const extension = path.extname(candidate).toLowerCase();
+  return (
+    {
+      ".json": "application/json",
+      ".png": "image/png",
+      ".pdf": "application/pdf",
+      ".pptx":
+        "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    }[extension] || "application/octet-stream"
+  );
+}
+
+function registerResources(server, options = {}) {
+  server.registerResource(
+    "ppt-session-artifact",
+    new ResourceTemplate("ppt://session/{sessionId}/{artifact}", {
+      list: undefined,
+    }),
+    {
+      description:
+        "Frozen semantic packages, plans, QA reports, output PPTX files, and contact sheets for a PPT reuse session.",
+    },
+    async (uri, variables) => {
+      const status = await getSessionStatus(String(variables.sessionId), options);
+      const candidate = status.artifacts?.[String(variables.artifact)];
+      if (!candidate || Array.isArray(candidate)) {
+        throw new Error("Unknown or indexed session artifact");
+      }
+      const bytes = await fs.readFile(candidate);
+      const mimeType = mimeFor(candidate);
+      return {
+        contents: [
+          mimeType.startsWith("text/") || mimeType === "application/json"
+            ? { uri: uri.href, mimeType, text: bytes.toString("utf8") }
+            : { uri: uri.href, mimeType, blob: bytes.toString("base64") },
+        ],
+      };
+    },
+  );
+  server.registerResource(
+    "ppt-session-indexed-artifact",
+    new ResourceTemplate("ppt://session/{sessionId}/{artifact}/{index}", {
+      list: undefined,
+    }),
+    { description: "A numbered generated slide preview." },
+    async (uri, variables) => {
+      const status = await getSessionStatus(String(variables.sessionId), options);
+      const values = status.artifacts?.[String(variables.artifact)];
+      const candidate = Array.isArray(values)
+        ? values[Number(variables.index)]
+        : undefined;
+      if (!candidate) throw new Error("Unknown indexed session artifact");
+      const bytes = await fs.readFile(candidate);
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: mimeFor(candidate),
+            blob: bytes.toString("base64"),
+          },
+        ],
+      };
+    },
+  );
+}
+
+export function createMcpServer(options = {}) {
+  const server = new McpServer(
+    { name: "ppt-template-reuse", version: engineVersion },
+    { capabilities: { logging: {}, resources: {} } },
+  );
+  registerTools(server, options);
+  registerResources(server, options);
+  return server;
+}
+
+export async function startStdio(options = {}) {
+  const server = createMcpServer(options);
+  await server.connect(new StdioServerTransport());
+  return server;
+}
+
+export async function startHttp({
+  host = "127.0.0.1",
+  port = 8765,
+  ...options
+} = {}) {
+  if (!["127.0.0.1", "localhost", "::1"].includes(host)) {
+    throw new Error("HTTP MCP binds to loopback only");
+  }
+  const app = createMcpExpressApp({ host });
+  app.post("/mcp", async (request, response) => {
+    const server = createMcpServer(options);
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+    });
+    try {
+      await server.connect(transport);
+      await transport.handleRequest(request, response, request.body);
+      response.on("close", async () => {
+        await transport.close();
+        await server.close();
+      });
+    } catch (error) {
+      if (!response.headersSent) {
+        response.status(500).json({
+          jsonrpc: "2.0",
+          error: { code: -32603, message: error.message },
+          id: null,
+        });
+      }
+    }
+  });
+  app.get("/health", (_request, response) =>
+    response.json({ ok: true, engineVersion }),
+  );
+  app.get("/mcp", (_request, response) => response.status(405).end());
+  app.delete("/mcp", (_request, response) => response.status(405).end());
+  return new Promise((resolve, reject) => {
+    const listener = app.listen(Number(port), host, (error) => {
+      if (error) reject(error);
+      else resolve({ app, listener, host, port: Number(port) });
+    });
+  });
+}
+
+const isMain =
+  process.argv[1] &&
+  pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url;
+if (isMain) {
+  startStdio().catch((error) => {
+    process.stderr.write(`${error.stack || error.message}\n`);
+    process.exit(1);
+  });
+}