explicai 0.1.0 → 0.2.1

package/dist/server/http.d.ts

@@ -1,7 +1,11 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 export declare class HttpError extends Error {
     readonly status: number;
-    constructor(status: number, message: string);
+    /** Identifica o erro para a interface traduzir (a mensagem fica em português para curl e MCP). */
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, 
+    /** Identifica o erro para a interface traduzir (a mensagem fica em português para curl e MCP). */
+    code?: string | undefined);
 }
 /** O que um handler devolve. O servidor transforma em resposta HTTP. */
 export type Reply = {
@@ -12,12 +16,16 @@ export type Reply = {
     kind: "file";
     path: string;
     cache: string;
+    untrusted: boolean;
 };
 export declare const json: (body: unknown, status?: number) => Reply;
-export declare const file: (filePath: string, cache?: string) => Reply;
-export declare function send(res: ServerResponse, reply: Reply): Promise<void>;
+/** `untrusted`: arquivo do manual (/files/), que pode ser um SVG com script; sai com CSP e sandbox. */
+export declare const file: (filePath: string, cache?: string, untrusted?: boolean) => Reply;
+export declare function send(res: ServerResponse, reply: Reply, req?: IncomingMessage): Promise<void>;
 export declare function sendJson(res: ServerResponse, status: number, body: unknown): void;
 export declare function readBody(req: IncomingMessage, limit: number): Promise<Uint8Array>;
 export declare function readJson(req: IncomingMessage): Promise<Record<string, unknown>>;
 /** Status HTTP para um erro vindo do core: "não encontrado" e arquivo inexistente viram 404, o resto 400. */
 export declare function statusOf(err: unknown): number;
+/** Texto do erro para a resposta: erro de arquivo do Node traz o caminho absoluto, então vira frase fixa. */
+export declare function publicMessage(err: unknown): string;

package/dist/server/http.js

@@ -1,14 +1,29 @@
-import { readFile } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
 import path from "node:path";
+import { pipeline } from "node:stream/promises";
+import { ExplicaiError } from "../core/errors.js";
 export class HttpError extends Error {
     status;
-    constructor(status, message) {
+    code;
+    constructor(status, message, 
+    /** Identifica o erro para a interface traduzir (a mensagem fica em português para curl e MCP). */
+    code) {
         super(message);
         this.status = status;
+        this.code = code;
     }
 }
 export const json = (body, status = 200) => ({ kind: "json", status, body });
-export const file = (filePath, cache = "no-cache") => ({ kind: "file", path: filePath, cache });
+/** `untrusted`: arquivo do manual (/files/), que pode ser um SVG com script; sai com CSP e sandbox. */
+export const file = (filePath, cache = "no-cache", untrusted = false) => ({
+    kind: "file",
+    path: filePath,
+    cache,
+    untrusted,
+});
+const RASTER = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp"]);
+const UNTRUSTED_CSP = "default-src 'none'; style-src 'unsafe-inline'; sandbox";
 const MIME = {
     ".html": "text/html; charset=utf-8",
     ".js": "text/javascript; charset=utf-8",
@@ -24,16 +39,30 @@ const MIME = {
     ".pdf": "application/pdf",
     ".md": "text/markdown; charset=utf-8",
 };
-export async function send(res, reply) {
+export async function send(res, reply, req) {
     if (reply.kind === "json")
         return sendJson(res, reply.status, reply.body);
-    const data = await readFile(reply.path);
-    res.writeHead(200, {
-        "content-type": MIME[path.extname(reply.path).toLowerCase()] ?? "application/octet-stream",
+    const info = await stat(reply.path); // ENOENT vira 404 no chamador, antes de qualquer cabeçalho
+    if (!info.isFile())
+        throw new HttpError(404, "Arquivo não encontrado.");
+    const ext = path.extname(reply.path).toLowerCase();
+    // ETag fraco por tamanho e mtime: barato, sem ler o arquivo.
+    const etag = `W/"${info.size.toString(16)}-${Math.floor(info.mtimeMs).toString(16)}"`;
+    const headers = {
+        etag,
         "cache-control": reply.cache,
         "x-content-type-options": "nosniff",
-    });
-    res.end(data);
+        ...(reply.untrusted && !RASTER.has(ext) ? { "content-security-policy": UNTRUSTED_CSP } : {}),
+    };
+    // shortcut: só um valor em If-None-Match (o do próprio navegador), sem lista nem "*"; Range/HEAD não tratados.
+    if (req?.headers["if-none-match"] === etag) {
+        res.writeHead(304, headers);
+        res.end();
+        return;
+    }
+    res.writeHead(200, { "content-type": MIME[ext] ?? "application/octet-stream", "content-length": info.size, ...headers });
+    // Erro no meio do envio ou cliente que abortou: o pipeline destrói os dois lados; os cabeçalhos já saíram.
+    await pipeline(createReadStream(reply.path), res).catch(() => { });
 }
 export function sendJson(res, status, body) {
     res.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
@@ -54,7 +83,19 @@ export async function readBody(req, limit) {
     return Buffer.concat(chunks);
 }
 export async function readJson(req) {
-    const text = Buffer.from(await readBody(req, 5 * 1024 * 1024)).toString("utf8");
+    const raw = await readBody(req, 5 * 1024 * 1024);
+    // Um POST text/plain de outro site não dispara preflight; exigir JSON fecha essa brecha. Corpo vazio não lê nada.
+    if (raw.length > 0 && !/^application\/json\s*(;|$)/i.test(req.headers["content-type"] ?? "")) {
+        throw new HttpError(415, "Envie o corpo como JSON, com o cabeçalho content-type: application/json.", "unsupported-media-type");
+    }
+    let text;
+    try {
+        // fatal: um cliente em Latin-1/cp1252 (curl no Windows) mandaria "í" como 0xED, e o decode comum o trocaria por U+FFFD gravado em disco.
+        text = new TextDecoder("utf-8", { fatal: true }).decode(raw);
+    }
+    catch {
+        throw new HttpError(400, "O corpo da requisição não está em UTF-8 válido. Envie o JSON em UTF-8.", "invalid-utf8");
+    }
     let data;
     try {
         data = text ? JSON.parse(text) : {};
@@ -71,8 +112,21 @@ export async function readJson(req) {
 export function statusOf(err) {
     if (err instanceof HttpError)
         return err.status;
+    if (err instanceof ExplicaiError && err.code === "disk-conflict")
+        return 409;
     const missing = (err instanceof Error && /não encontrad/i.test(err.message)) ||
-        (typeof err === "object" && err !== null && err.code === "ENOENT");
+        ["ENOENT", "EISDIR"].includes(err?.code ?? "");
     return missing ? 404 : 400;
 }
+const FILE_ERRORS = {
+    ENOENT: "Arquivo não encontrado.",
+    EISDIR: "Arquivo não encontrado.",
+    EACCES: "Sem permissão para acessar o arquivo.",
+    EPERM: "Sem permissão para acessar o arquivo.",
+};
+/** Texto do erro para a resposta: erro de arquivo do Node traz o caminho absoluto, então vira frase fixa. */
+export function publicMessage(err) {
+    const fixed = FILE_ERRORS[err?.code ?? ""];
+    return fixed ?? (err instanceof Error ? err.message : String(err));
+}
 //# sourceMappingURL=http.js.map

package/dist/server/index.js

@@ -1,29 +1,59 @@
 import { createServer } from "node:http";
-import { HttpError, send, sendJson, statusOf } from "./http.js";
+import { ExplicaiError } from "../core/errors.js";
+import { errorPage, pickLang } from "./errorPage.js";
+import { HttpError, publicMessage, send, sendJson, statusOf } from "./http.js";
 import { matchRoute } from "./router.js";
 import { assetRoutes } from "./routes/assets.js";
 import { exportRoutes } from "./routes/export.js";
+import { fontRoutes } from "./routes/fonts.js";
 import { manualRoutes } from "./routes/manuals.js";
 import { pageRoutes } from "./routes/pages.js";
 import { versionRoutes } from "./routes/versions.js";
 import { webRoutes } from "./routes/web.js";
 import { assertLocalRequest } from "./security.js";
 /** A ordem importa: a rota genérica do editor (`/*`) fica por último. */
-const routes = [...manualRoutes, ...pageRoutes, ...versionRoutes, ...exportRoutes, ...assetRoutes, ...webRoutes];
+const routes = [
+    ...manualRoutes,
+    ...pageRoutes,
+    ...versionRoutes,
+    ...exportRoutes,
+    ...fontRoutes,
+    ...assetRoutes,
+    ...webRoutes,
+];
+/** Um `%` malformado no endereço é erro de quem pediu (400 com código estável), não falha do servidor. */
+function decodeSegment(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        throw new HttpError(400, "O endereço pedido tem um % malformado. Confira o endereço e tente de novo.", "malformed-url");
+    }
+}
 export function createStudioServer(opts) {
     return createServer(async (req, res) => {
         try {
             assertLocalRequest(req);
             const url = new URL(req.url ?? "/", "http://localhost");
-            const segments = url.pathname.split("/").filter(Boolean).map(decodeURIComponent);
+            const segments = url.pathname.split("/").filter(Boolean).map(decodeSegment);
             const method = req.method ?? "GET";
             const match = matchRoute(routes, method, segments);
             if (!match)
                 throw new HttpError(segments[0] === "api" ? 405 : 404, "Rota não encontrada.");
-            await send(res, await match.route.handle({ req, url, params: match.params, rest: match.rest, opts }));
+            await send(res, await match.route.handle({ req, url, params: match.params, rest: match.rest, opts }), req);
         }
         catch (err) {
-            sendJson(res, statusOf(err), { error: err instanceof Error ? err.message : String(err) });
+            const { code, params } = err instanceof ExplicaiError ? err : {};
+            const errorCode = code ?? (err instanceof HttpError ? err.code : undefined);
+            const status = statusOf(err);
+            // Quem abre o Studio no navegador recebe uma página legível; a API e os arquivos continuam em JSON.
+            const [first] = (req.url ?? "/").split("?")[0]?.split("/").filter(Boolean) ?? [];
+            if (first !== "api" && first !== "files" && req.headers.accept?.includes("text/html")) {
+                const html = errorPage(status, errorCode ?? (status === 404 ? "not-found" : "error"), pickLang(req.headers["accept-language"]));
+                res.writeHead(status, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+                return void res.end(html);
+            }
+            sendJson(res, status, { error: publicMessage(err), code: errorCode, params });
         }
     });
 }

package/dist/server/routes/assets.js

@@ -1,4 +1,4 @@
-import { cleanUnusedAssets, findUnusedAssets, readAnnotations, resolveInside, saveAsset, writeAnnotations, } from "../../core/index.js";
+import { cleanUnusedAssets, findUnusedAssets, insideGitRepo, readAnnotations, redactAsset, resolveInsideReal, saveAsset, writeAnnotations, } from "../../core/index.js";
 import { file, json, readBody, readJson } from "../http.js";
 import { manualDir } from "../workspace.js";
 const MAX_UPLOAD = 20 * 1024 * 1024;
@@ -22,6 +22,21 @@ export const assetRoutes = [
         path: "/api/manuals/:slug/annotations",
         handle: async (ctx) => json(await writeAnnotations(manualDir(ctx), ctx.url.searchParams.get("asset") ?? "", await readJson(ctx.req))),
     },
+    {
+        // Troca o print pela versão com as tarjas já pintadas (o navegador desenha) e apaga o original.
+        method: "POST",
+        path: "/api/manuals/:slug/assets/redact",
+        handle: async (ctx) => {
+            const asset = ctx.url.searchParams.get("asset") ?? "";
+            await redactAsset(manualDir(ctx), asset, await readBody(ctx.req, MAX_UPLOAD));
+            return json({ path: asset });
+        },
+    },
+    {
+        method: "GET",
+        path: "/api/manuals/:slug/git",
+        handle: async (ctx) => json({ git: await insideGitRepo(manualDir(ctx)) }),
+    },
     {
         // Imagens e marcações que nenhuma página, versão ou item da lixeira usa.
         method: "GET",
@@ -38,7 +53,11 @@ export const assetRoutes = [
         // Imagens do manual, usadas pelo editor: /files/<manual>/assets/<arquivo>
         method: "GET",
         path: "/files/:slug/*",
-        handle: (ctx) => file(resolveInside(manualDir(ctx), ctx.rest)),
+        // Só raster de assets/ (nome único, gravado uma vez) fica em cache; manual.json, logo e .md revalidam por ETag.
+        handle: async (ctx) => {
+            const cacheable = /^assets\/[^/]+\.(png|jpe?g|gif|webp)$/i.test(ctx.rest);
+            return file(await resolveInsideReal(manualDir(ctx), ctx.rest), cacheable ? "private, max-age=3600" : "no-cache", true);
+        },
     },
 ];
 //# sourceMappingURL=assets.js.map

package/dist/server/routes/export.js

@@ -1,5 +1,5 @@
-import { EXPORT_FORMATS, exportManual, setManualTheme } from "../../core/index.js";
-import { HttpError, json, readJson } from "../http.js";
+import { EXPORT_FORMATS, exportManual, logoSizeError, setManualLogo, setManualTheme, } from "../../core/index.js";
+import { HttpError, json, readBody, readJson } from "../http.js";
 import { manualDir, optionalString } from "../workspace.js";
 export const exportRoutes = [
     {
@@ -17,17 +17,27 @@ export const exportRoutes = [
         },
     },
     {
-        // { accent: "#2b4fe0" } escolhe a cor do manual exportado; { accent: null } volta à da marca.
+        // Muda só os campos enviados: { accent?, text?, highlight?, headings?: { cover?, page?, h1?, h2?, h3? } },
+        // cada um em hexadecimal ou null para voltar à cor da marca. O core confere formato e contraste (400).
         method: "PUT",
         path: "/api/manuals/:slug/theme",
         handle: async (ctx) => {
-            const body = await readJson(ctx.req);
-            const accent = body.accent === null ? undefined : optionalString(body.accent);
-            if (accent === undefined && body.accent !== null)
-                throw new HttpError(400, "Informe accent (texto ou null).");
-            await setManualTheme(manualDir(ctx), accent ? { accent } : {});
+            await setManualTheme(manualDir(ctx), await readJson(ctx.req));
             return json({ ok: true });
         },
     },
+    {
+        // Corpo = o arquivo do logo (PNG, JPG ou SVG, até 1 MB), nome em ?name=. Guarda em assets/ e põe no tema.
+        // O limite de leitura é maior que o do logo para o core recusar com o motivo.
+        method: "POST",
+        path: "/api/manuals/:slug/logo",
+        handle: async (ctx) => {
+            const name = ctx.url.searchParams.get("name") ?? "logo.png";
+            const data = await readBody(ctx.req, 2 * 1024 * 1024).catch((err) => {
+                throw err instanceof HttpError && err.status === 413 ? logoSizeError() : err;
+            });
+            return json({ path: await setManualLogo(manualDir(ctx), name, data) }, 201);
+        },
+    },
 ];
 //# sourceMappingURL=export.js.map

package/dist/server/routes/fonts.d.ts

@@ -0,0 +1,3 @@
+import type { Route } from "../router.js";
+/** As fontes que o manual exportado pode usar, para o Studio mostrar a prévia de cada uma. */
+export declare const fontRoutes: Route[];

package/dist/server/routes/fonts.js

@@ -0,0 +1,24 @@
+import { fileURLToPath } from "node:url";
+import { FONTS, FONTS_DIR, fontFiles } from "../../core/index.js";
+import { file, HttpError, json } from "../http.js";
+const FILES = new Set(FONTS.flatMap((f) => fontFiles(f).map((x) => x.file)));
+/** As fontes que o manual exportado pode usar, para o Studio mostrar a prévia de cada uma. */
+export const fontRoutes = [
+    {
+        method: "GET",
+        path: "/api/fonts",
+        handle: () => json(FONTS.map((f) => ({ id: f.id, family: f.family, kind: f.kind, italic: f.italic, files: fontFiles(f) }))),
+    },
+    {
+        method: "GET",
+        path: "/api/fonts/:file",
+        handle: ({ params }) => {
+            const name = params.file ?? "";
+            // Só os arquivos da lista: o nome vem da URL e não vira caminho de disco.
+            if (!FILES.has(name))
+                throw new HttpError(404, "Fonte não encontrada.");
+            return file(fileURLToPath(new URL(name, FONTS_DIR)), "max-age=86400");
+        },
+    },
+];
+//# sourceMappingURL=fonts.js.map

package/dist/server/routes/pages.js

@@ -37,7 +37,9 @@ export const pageRoutes = [
                 ...(text === undefined ? {} : { body: text }),
                 ...(status === undefined ? {} : { status }),
             };
-            return json(await updatePage(manualDir(ctx), ctx.params.id ?? "", patch));
+            const fileName = body.fileName === "keep" || body.fileName === "sync" ? body.fileName : undefined;
+            const ifMatch = ctx.req.headers["if-match"];
+            return json(await updatePage(manualDir(ctx), ctx.params.id ?? "", patch, { fileName, ifMatch }));
         },
     },
     {

package/dist/server/routes/web.js

@@ -16,7 +16,13 @@ export const webRoutes = [
             // Só os arquivos com hash no nome (assets/) podem ficar em cache; o index.html muda a cada build.
             if (isFile && rest.startsWith("assets/"))
                 return file(target, "max-age=31536000, immutable");
-            return file(isFile ? target : path.join(opts.webDir, "index.html"));
+            if (isFile)
+                return file(target);
+            const index = path.join(opts.webDir, "index.html");
+            const hasIndex = await stat(index).then((s) => s.isFile(), () => false);
+            if (!hasIndex)
+                throw new HttpError(500, "O editor não foi encontrado: rode npm run build.", "web-missing");
+            return file(index);
         },
     },
 ];

package/dist/server/security.d.ts

@@ -1,6 +1,6 @@
 import type { IncomingMessage } from "node:http";
 /**
- * O Studio só atende o próprio computador. Checar Host e Origin impede que um site aberto
+ * O Studio só atende o próprio computador. Checar Host e Origin (que deve ser igual ao Host) impede que um site aberto
  * no navegador use o Studio (DNS rebinding e requisições de outra origem).
  */
 export declare function assertLocalRequest(req: IncomingMessage): void;

package/dist/server/security.js

@@ -1,16 +1,17 @@
 import { HttpError } from "./http.js";
 const LOCAL_HOSTS = ["localhost", "127.0.0.1", "[::1]"];
-const LOCAL_ORIGIN = /^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/;
 /**
- * O Studio só atende o próprio computador. Checar Host e Origin impede que um site aberto
+ * O Studio só atende o próprio computador. Checar Host e Origin (que deve ser igual ao Host) impede que um site aberto
  * no navegador use o Studio (DNS rebinding e requisições de outra origem).
  */
 export function assertLocalRequest(req) {
-    const host = (req.headers.host ?? "").replace(/:\d+$/, "");
+    const fullHost = req.headers.host ?? "";
+    const host = fullHost.replace(/:\d+$/, "");
     if (!LOCAL_HOSTS.includes(host))
-        throw new HttpError(403, "Acesso permitido só a partir deste computador.");
+        throw new HttpError(403, "Acesso permitido só a partir deste computador.", "forbidden-host");
     const origin = req.headers.origin;
-    if (origin && !LOCAL_ORIGIN.test(origin))
-        throw new HttpError(403, "Origem não permitida.");
+    // Mesma origem do Host, porta inclusa. O proxy do Vite não reescreve o Host (changeOrigin desligado), então 5173 bate com 5173.
+    if (origin && origin !== `http://${fullHost}`)
+        throw new HttpError(403, "Origem não permitida.", "forbidden-origin");
 }
 //# sourceMappingURL=security.js.map