A local-first multi-agent app development platform, built on PenguinHarness
/**
* Word previews: the .docx → Markdown extraction and the route that serves it.
*
* The extraction:
* - reads `word/document.xml` out of the zip and lays its paragraphs out as Markdown: headings
* from the paragraph's own style or outline level, list items indented by their level,
* bold/italic runs, tables as GFM tables, and the XML entities and line breaks Word writes;
* - escapes what Markdown would otherwise read as syntax, so document text stays text, while the
* markers it writes itself are not escaped twice;
* - refuses anything that is not a .docx (a zip without the document part, or not a zip at
* all), and cuts the output at its character cap with `truncated`.
*
* The route (`files/preview-text`, in both scopes):
* - answers a .docx with Markdown, an ETag of the read version, `no-store`, and
* `X-Content-Truncated` when the extraction was cut;
* - answers a legacy .doc with 415 `doc_legacy` and any other type with 415
* `preview_unavailable` — this route serves an extraction, never the file;
* - answers an outsider with 404, and never touches a Workspace it was not given.
*/
import fs from "node:fs/promises";
import path from "node:path";
import { strToU8, zipSync } from "fflate";
import { afterAll, beforeAll, describe, expect, it } from "vitest";
import {
DOCX_PREVIEW_MAX_CHARS,
DocxPreviewError,
docxToMarkdown,
} from "../src/services/docx-preview.js";
import type { ProjectCreateResponse, SessionCreateResponse } from "../src/api/types.js";
import { apiClient, createTestApp, provisionUser } from "./helpers.js";
import type { TestApp } from "./helpers.js";
/** A .docx as Word writes one: a zip whose `word/document.xml` is the body. */
function docx(body: string, extra: Record<string, Uint8Array> = {}): Uint8Array {
return zipSync({
"[Content_Types].xml": strToU8("<Types/>"),
"word/document.xml": strToU8(
`<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:body>${body}</w:body></w:document>`,
),
...extra,
});
}
/** A run of plain text. */
const run = (text: string): string => `<w:r><w:t xml:space="preserve">${text}</w:t></w:r>`;
/** A paragraph with the given inner XML. */
const para = (inner: string, props = ""): string =>
`<w:p>${props === "" ? "" : `<w:pPr>${props}</w:pPr>`}${inner}</w:p>`;
describe("docxToMarkdown", () => {
it("lays paragraphs out as Markdown: headings by style and outline level, bold and italic runs", () => {
const body = [
para(run("标题一"), '<w:pStyle w:val="Heading1"/>'),
para(
"<w:r><w:rPr><w:b/></w:rPr><w:t>粗体</w:t></w:r><w:r><w:t>与</w:t></w:r><w:r><w:rPr><w:i/></w:rPr><w:t>斜体</w:t></w:r>",
),
para(run("二级标题"), '<w:outlineLvl w:val="1"/>'),
para(run("普通段落")),
].join("");
expect(docxToMarkdown(docx(body)).markdown).toBe(
["# 标题一", "**粗体**与*斜体*", "## 二级标题", "普通段落"].join("\n\n"),
);
});
it("indents list items by their own level and keeps tables as GFM tables", () => {
const body = [
para(run("第一项"), '<w:numPr><w:ilvl w:val="0"/></w:numPr>'),
para(run("第二层"), '<w:numPr><w:ilvl w:val="1"/></w:numPr>'),
`<w:tbl>${[
"<w:tr><w:tc><w:p><w:r><w:t>指标</w:t></w:r></w:p></w:tc><w:tc><w:p><w:r><w:t>数据</w:t></w:r></w:p></w:tc></w:tr>",
"<w:tr><w:tc><w:p><w:r><w:t>出货量</w:t></w:r></w:p></w:tc><w:tc><w:p><w:r><w:t>1477 万台</w:t></w:r></w:p></w:tc></w:tr>",
].join("")}</w:tbl>`,
].join("");
expect(docxToMarkdown(docx(body)).markdown).toBe(
["- 第一项", " - 第二层", "| 指标 | 数据 |\n| --- | --- |\n| 出货量 | 1477 万台 |"].join(
"\n\n",
),
);
});
it("decodes entities and line breaks, and escapes text that would read as Markdown", () => {
const body = [
para(run("A & B <tag> 中")),
para(run("# 不是标题")),
para("<w:r><w:t>第一行</w:t><w:br/><w:t>第二行</w:t></w:r>"),
para(run("a*b_c[d]")),
].join("");
const markdown = docxToMarkdown(docx(body)).markdown;
expect(markdown).toContain("A & B \\<tag\\> 中");
// The leading "#" would have made a heading; it is defused, not promoted.
expect(markdown).toContain("\\# 不是标题");
expect(markdown).toContain("第一行 第二行");
expect(markdown).toContain("a\\*b\\_c\\[d\\]");
});
it("reads only the document part — a large sibling entry is never inflated", () => {
const body = para(run("正文"));
const archive = docx(body, { "word/media/image1.png": new Uint8Array(4 * 1024 * 1024) });
expect(docxToMarkdown(archive).markdown).toBe("正文");
});
it("cuts the output at its character cap and says so", () => {
const body = para(run("长".repeat(500)));
const out = docxToMarkdown(docx(body), 100);
expect(out.truncated).toBe(true);
expect(out.markdown.length).toBe(100);
expect(docxToMarkdown(docx(body)).truncated).toBe(false);
expect(DOCX_PREVIEW_MAX_CHARS).toBe(200_000);
});
it("refuses what it cannot read: a zip without the document part, and bytes that are not a zip", () => {
const empty = zipSync({ "word/styles.xml": strToU8("<styles/>") });
expect(() => docxToMarkdown(empty)).toThrow(DocxPreviewError);
expect(() => docxToMarkdown(strToU8("not a zip at all"))).toThrow(DocxPreviewError);
});
});
/** The route: one owner, one outsider, one Session (and so one Workspace) per case. */
let t: TestApp;
let owner: ReturnType<typeof apiClient>;
let outsider: ReturnType<typeof apiClient>;
let projectId: string;
beforeAll(async () => {
t = await createTestApp();
owner = apiClient(t.app, (await provisionUser(t.app, "owner")).cookie);
outsider = apiClient(t.app, (await provisionUser(t.app, "outsider")).cookie);
const created = (await (
await owner.post("/api/projects", { projectId: "owner-docx", name: "project" })
).json()) as ProjectCreateResponse;
projectId = created.project.projectId;
await owner.put(`/api/projects/${projectId}/models`, {
defaultModel: { provider: "anthropic", modelId: "claude-sonnet-4-6" },
models: [{ provider: "anthropic", modelId: "claude-sonnet-4-6", contextWindow: 128000 }],
});
});
afterAll(async () => {
await t.cleanup();
});
async function sessionWithWords(): Promise<{ sessionId: string; workspace: string }> {
const sess = (await (
await owner.post(`/api/projects/${projectId}/agents/default_agent/sessions`, {})
).json()) as SessionCreateResponse;
const workspace = sess.session.workspace;
await fs.writeFile(path.join(workspace, "doc.docx"), Buffer.from(docx(para(run("你好,Word")))));
await fs.writeFile(path.join(workspace, "old.doc"), Buffer.from("%D0CF11E0 binary", "latin1"));
await fs.writeFile(path.join(workspace, "notes.md"), "# md");
return { sessionId: sess.session.sessionId, workspace };
}
describe("files/preview-text route", () => {
it("answers a .docx with Markdown and the read's version; no cache, no sniffing", async () => {
const { sessionId } = await sessionWithWords();
const res = await owner.get(`/api/sessions/${sessionId}/files/preview-text?path=doc.docx`);
expect(res.status).toBe(200);
expect(res.headers.get("content-type")).toContain("text/markdown");
expect(res.headers.get("x-content-type-options")).toBe("nosniff");
expect(res.headers.get("cache-control")).toBe("no-store");
expect(res.headers.get("etag")).toMatch(/^W\/"\d+-\d+"$/);
expect(res.headers.get("x-content-truncated")).toBeNull();
expect(await res.text()).toBe("你好,Word");
});
it("names the two refusals apart: a legacy .doc says so, anything else is not extracted", async () => {
const { sessionId } = await sessionWithWords();
const legacy = await owner.get(`/api/sessions/${sessionId}/files/preview-text?path=old.doc`);
expect(legacy.status).toBe(415);
expect(await legacy.json()).toEqual({
error: { code: "doc_legacy", message: expect.any(String) },
});
const other = await owner.get(`/api/sessions/${sessionId}/files/preview-text?path=notes.md`);
expect(other.status).toBe(415);
expect(await other.json()).toEqual({
error: { code: "preview_unavailable", message: expect.any(String) },
});
});
it("serves the directory scope too, and answers an outsider with 404", async () => {
const { sessionId, workspace } = await sessionWithWords();
const byDir = await owner.get(
`/api/projects/${projectId}/workspace-files/preview-text?workspace=${encodeURIComponent(workspace)}&path=doc.docx`,
);
expect(byDir.status).toBe(200);
expect(await byDir.text()).toBe("你好,Word");
const nope = await outsider.get(`/api/sessions/${sessionId}/files/preview-text?path=doc.docx`);
expect(nope.status).toBe(404);
});
});