explicai 0.0.0-stage → 0.2.0

package/dist/core/export/theme.js

@@ -0,0 +1,140 @@
+import { ExplicaiError } from "../errors.js";
+import { HEADING_SLOTS } from "../types.js";
+import { contrast, contrastWithWhite, HEX, muted, overWhite, withAlpha } from "./color.js";
+import { DEFAULT_HEADINGS_FONT, DEFAULT_TEXT_FONT, FONTS, fontById, fontFaceCss, fontStack, MONO, } from "./fonts.js";
+import { checkLogoPath } from "./logo.js";
+/** Contraste mínimo do texto com o fundo (WCAG AA). */
+export const MIN_CONTRAST = 4.5;
+/** Valores de hoje: o manual sem `theme` exporta com estes. */
+export const DEFAULT_TEXT = "#151a33";
+export const DEFAULT_ACCENT = "#2b4fe0";
+export const DEFAULT_HIGHLIGHT = "#ffd43b";
+/** Opacidade do marca-texto sobre o papel (a mesma do CSS do export). */
+const HIGHLIGHT_ALPHA = 0.55;
+const SLOT_NAMES = {
+    cover: "título da capa",
+    page: "título da página",
+    h1: "título de nível 1",
+    h2: "título de nível 2",
+    h3: "título de nível 3",
+};
+const num = (n) => n.toFixed(1).replace(".", ",");
+function hexOf(value, label) {
+    if (value === null)
+        return null;
+    if (typeof value !== "string" || !HEX.test(value))
+        throw new Error(`Cor inválida em ${label}: use o formato #2b4fe0.`);
+    return value.toLowerCase();
+}
+function readable(hex, label) {
+    const c = contrastWithWhite(hex);
+    if (c < MIN_CONTRAST) {
+        throw new ExplicaiError("low-contrast", `A cor de ${label} tem contraste ${num(c)}:1 com o branco; o mínimo é ${num(MIN_CONTRAST)}:1. Escolha uma cor mais escura.`, { label, ratio: c, min: MIN_CONTRAST });
+    }
+    return hex;
+}
+/** A fonte da lista com esse nome. O texto precisa de uma com itálico empacotado. */
+function fontOf(id, role) {
+    const font = typeof id === "string" ? fontById(id) : undefined;
+    const valid = FONTS.filter((f) => role === "headings" || f.italic);
+    if (!font || !valid.includes(font)) {
+        throw new Error(`Fonte fora da lista: ${String(id)}. Use uma destas: ${valid.map((f) => f.id).join(", ")}.`);
+    }
+    return font;
+}
+/** As fontes que o tema usa (as da marca, onde não houve escolha). */
+export function themeFonts(theme) {
+    return {
+        text: fontById(theme?.fonts?.text ?? DEFAULT_TEXT_FONT),
+        headings: fontById(theme?.fonts?.headings ?? DEFAULT_HEADINGS_FONT),
+    };
+}
+/** Aplica `patch` sobre o tema atual e confere tudo. Devolve o tema novo; o que não mudou continua igual. */
+export function mergeTheme(current, patch) {
+    const next = { ...current, headings: { ...current?.headings }, fonts: { ...current?.fonts } };
+    const set = (key, label, check) => {
+        if (patch[key] === undefined)
+            return;
+        const hex = hexOf(patch[key], label);
+        if (hex === null)
+            delete next[key];
+        else
+            next[key] = check ? readable(hex, label) : hex;
+    };
+    set("accent", "destaque", true);
+    set("text", "texto", true);
+    set("highlight", "realce", false);
+    if (patch.headings === null)
+        next.headings = {};
+    else if (patch.headings) {
+        for (const slot of HEADING_SLOTS) {
+            const value = patch.headings[slot];
+            if (value === undefined)
+                continue;
+            const hex = hexOf(value, SLOT_NAMES[slot]);
+            if (hex === null)
+                delete next.headings?.[slot];
+            else if (next.headings)
+                next.headings[slot] = readable(hex, SLOT_NAMES[slot]);
+        }
+    }
+    if (patch.fonts === null)
+        next.fonts = {};
+    else if (patch.fonts) {
+        for (const role of ["text", "headings"]) {
+            const id = patch.fonts[role];
+            if (id === undefined)
+                continue;
+            if (id === null)
+                delete next.fonts?.[role];
+            else if (next.fonts)
+                next.fonts[role] = fontOf(id, role).id;
+        }
+    }
+    if (patch.logo === null)
+        delete next.logo;
+    else if (patch.logo !== undefined)
+        next.logo = checkLogoPath(patch.logo);
+    // O realce é fundo: o texto por cima precisa continuar legível.
+    if (next.highlight) {
+        const c = contrast(overWhite(next.highlight, HIGHLIGHT_ALPHA), next.text ?? DEFAULT_TEXT);
+        if (c < MIN_CONTRAST) {
+            throw new ExplicaiError("low-contrast-highlight", `O texto sobre o realce tem contraste ${num(c)}:1; o mínimo é ${num(MIN_CONTRAST)}:1. Escolha um realce mais claro.`, { ratio: c, min: MIN_CONTRAST });
+        }
+    }
+    if (!Object.keys(next.headings ?? {}).length)
+        delete next.headings;
+    if (!Object.keys(next.fonts ?? {}).length)
+        delete next.fonts;
+    return next;
+}
+/** Variáveis CSS do tema, só as que mudam. Vazio quando o manual usa as cores da marca. */
+export function themeCss(theme) {
+    if (!theme)
+        return "";
+    const v = [];
+    if (theme.accent)
+        v.push(`--accent:${theme.accent}`, `--anotacao:${theme.accent}`, `--anotacao-fundo:${withAlpha(theme.accent, 0.08)}`);
+    if (theme.text)
+        v.push(`--tinta:${theme.text}`, `--grafite:${muted(theme.text)}`);
+    if (theme.highlight) {
+        v.push(`--marca:${theme.highlight}`, `--marca-faixa:${withAlpha(theme.highlight, HIGHLIGHT_ALPHA)}`, `--marca-halo:${withAlpha(theme.highlight, 0.3)}`);
+    }
+    for (const slot of HEADING_SLOTS)
+        if (theme.headings?.[slot])
+            v.push(`--t-${slot}:${theme.headings[slot]}`);
+    const fonts = themeFonts(theme);
+    if (theme.fonts?.text)
+        v.push(`--texto:${fontStack(fonts.text)}`);
+    if (theme.fonts?.headings)
+        v.push(`--display:${fontStack(fonts.headings)}`);
+    return v.length ? `:root{${v.join(";")}}` : "";
+}
+/** As fontes que vão no export: texto, títulos (sem repetir) e a de código. */
+export function usedFonts(theme) {
+    const { text, headings } = themeFonts(theme);
+    return [...new Set([text, headings, MONO])];
+}
+/** `@font-face` das fontes usadas, no mesmo formato do export. */
+export const fontFacesCss = (theme) => usedFonts(theme).map(fontFaceCss).join("\n");
+//# sourceMappingURL=theme.js.map

package/dist/core/frontmatter.d.ts

@@ -0,0 +1,5 @@
+export declare function splitFrontmatter(text: string): {
+    data: Record<string, unknown>;
+    body: string;
+};
+export declare function joinFrontmatter(data: Record<string, unknown>, body: string): string;

package/dist/core/frontmatter.js

@@ -0,0 +1,17 @@
+import { parse, stringify } from "yaml";
+const FENCE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+export function splitFrontmatter(text) {
+    const match = FENCE.exec(text);
+    if (!match)
+        return { data: {}, body: text };
+    const data = parse(match[1] ?? "");
+    if (data !== null && (typeof data !== "object" || Array.isArray(data))) {
+        throw new Error("Frontmatter inválido: esperado um mapa YAML.");
+    }
+    // joinFrontmatter põe uma linha em branco depois do bloco; ela não faz parte do corpo.
+    return { data: (data ?? {}), body: text.slice(match[0].length).replace(/^\r?\n/, "") };
+}
+export function joinFrontmatter(data, body) {
+    return `---\n${stringify(data).trimEnd()}\n---\n\n${body.replace(/^\n+/, "")}`;
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/core/fs.d.ts

@@ -0,0 +1,13 @@
+/** Grava num arquivo temporário e renomeia, para um travamento no meio não deixar o arquivo pela metade. */
+export declare function atomicWrite(file: string, content: string): Promise<void>;
+/** Lê UTF-8 sem o BOM que o Bloco de Notas e alguns editores do Windows põem no começo: ele quebraria o JSON e o frontmatter. */
+export declare function readText(file: string): Promise<string>;
+/** Barreira de confiança: caminhos vêm do Agent e do navegador, então nada pode sair da pasta base. */
+export declare function resolveInside(dir: string, relative: string): string;
+/** Como `resolveInside`, mas segue links simbólicos: um link dentro do manual que aponta para fora é recusado. O arquivo precisa existir. */
+export declare function resolveInsideReal(dir: string, relative: string): Promise<string>;
+/** `base.ext`, ou `base-2.ext`, `base-3.ext`… se já existir. */
+export declare function uniquePath(parent: string, base: string, ext: string): Promise<string>;
+export declare function exists(p: string): Promise<boolean>;
+/** Caminho relativo com `/`, igual em qualquer sistema, para gravar em manual.json e no Markdown. */
+export declare function relativePosix(from: string, to: string): string;

package/dist/core/fs.js

@@ -0,0 +1,45 @@
+import { randomUUID } from "node:crypto";
+import { readFile, realpath, rename, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+/** Grava num arquivo temporário e renomeia, para um travamento no meio não deixar o arquivo pela metade. */
+export async function atomicWrite(file, content) {
+    const tmp = `${file}.${randomUUID()}.tmp`;
+    await writeFile(tmp, content, "utf8");
+    await rename(tmp, file);
+}
+/** Lê UTF-8 sem o BOM que o Bloco de Notas e alguns editores do Windows põem no começo: ele quebraria o JSON e o frontmatter. */
+export async function readText(file) {
+    return (await readFile(file, "utf8")).replace(/^/, "");
+}
+/** Barreira de confiança: caminhos vêm do Agent e do navegador, então nada pode sair da pasta base. */
+export function resolveInside(dir, relative) {
+    const root = path.resolve(dir);
+    const abs = path.resolve(root, relative);
+    if (abs !== root && !abs.startsWith(root + path.sep))
+        throw new Error(`Caminho fora do manual: ${relative}`);
+    return abs;
+}
+/** Como `resolveInside`, mas segue links simbólicos: um link dentro do manual que aponta para fora é recusado. O arquivo precisa existir. */
+export async function resolveInsideReal(dir, relative) {
+    const abs = resolveInside(dir, relative);
+    const [real, root] = await Promise.all([realpath(abs), realpath(path.resolve(dir))]);
+    if (real !== root && !real.startsWith(root + path.sep))
+        throw new Error(`Caminho fora do manual: ${relative}`);
+    return abs;
+}
+/** `base.ext`, ou `base-2.ext`, `base-3.ext`… se já existir. */
+export async function uniquePath(parent, base, ext) {
+    for (let i = 1;; i++) {
+        const candidate = path.join(parent, `${i === 1 ? base : `${base}-${i}`}${ext}`);
+        if (!(await exists(candidate)))
+            return candidate;
+    }
+}
+export async function exists(p) {
+    return stat(p).then(() => true, () => false);
+}
+/** Caminho relativo com `/`, igual em qualquer sistema, para gravar em manual.json e no Markdown. */
+export function relativePosix(from, to) {
+    return path.relative(from, to).split(path.sep).join("/");
+}
+//# sourceMappingURL=fs.js.map

package/dist/core/index.d.ts

@@ -0,0 +1,14 @@
+export { emptyAnnotations, parseAnnotations } from "./annotations.js";
+export { cleanUnusedAssets, findUnusedAssets, readAnnotations, saveAsset, writeAnnotations } from "./assets.js";
+export { ExplicaiError } from "./errors.js";
+export { FONTS, FONTS_DIR, type FontSpec, fontFiles } from "./export/fonts.js";
+export { EXPORT_DIR, EXPORT_FORMATS, type ExportFormat, type ExportResult, exportManual, findBrowser, logoSizeError, setManualLogo, setManualTheme, } from "./export/index.js";
+export { resolveInside, resolveInsideReal } from "./fs.js";
+export { createManual, listManuals, readManual } from "./manuals.js";
+export { addPage, movePage, type PageTreeNode, readPage, readPageTree, updatePage } from "./pages.js";
+export { insideGitRepo, redactAsset } from "./redact.js";
+export { slugify } from "./text.js";
+export { listTrash, removePage, restorePage, TRASH_DIR, type TrashItem } from "./trash.js";
+export { flatten } from "./tree.js";
+export * from "./types.js";
+export { listVersions, publishVersion, readVersion, restoreVersion, saveVersion, VERSIONS_DIR, type Version, type VersionInfo, } from "./versions.js";

package/dist/core/index.js

@@ -0,0 +1,15 @@
+export { emptyAnnotations, parseAnnotations } from "./annotations.js";
+export { cleanUnusedAssets, findUnusedAssets, readAnnotations, saveAsset, writeAnnotations } from "./assets.js";
+export { ExplicaiError } from "./errors.js";
+export { FONTS, FONTS_DIR, fontFiles } from "./export/fonts.js";
+export { EXPORT_DIR, EXPORT_FORMATS, exportManual, findBrowser, logoSizeError, setManualLogo, setManualTheme, } from "./export/index.js";
+export { resolveInside, resolveInsideReal } from "./fs.js";
+export { createManual, listManuals, readManual } from "./manuals.js";
+export { addPage, movePage, readPage, readPageTree, updatePage } from "./pages.js";
+export { insideGitRepo, redactAsset } from "./redact.js";
+export { slugify } from "./text.js";
+export { listTrash, removePage, restorePage, TRASH_DIR } from "./trash.js";
+export { flatten } from "./tree.js";
+export * from "./types.js";
+export { listVersions, publishVersion, readVersion, restoreVersion, saveVersion, VERSIONS_DIR, } from "./versions.js";
+//# sourceMappingURL=index.js.map

package/dist/core/manuals.d.ts

@@ -0,0 +1,23 @@
+import { type Manual, type ManualMeta } from "./types.js";
+export declare const PAGES_DIR = "pages";
+export declare const ASSETS_DIR = "assets";
+export declare function createManual(workspace: string, opts: {
+    title: string;
+    language: string;
+}): Promise<Manual>;
+/**
+ * Manuais são as subpastas diretas do workspace que têm manual.json.
+ * Manual com manual.json ilegível fica de fora da lista, para um manual estragado não impedir
+ * de abrir os outros. Abrir ele pelo endereço mostra o erro de readManual.
+ */
+export declare function listManuals(workspace: string): Promise<Manual[]>;
+export declare function readManual(dir: string): Promise<ManualMeta>;
+export declare function writeManual(dir: string, meta: ManualMeta): Promise<void>;
+/**
+ * Lê o manual, aplica a mudança e grava de volta. Concentra o ciclo ler-alterar-gravar da árvore.
+ * Chamadas da mesma pasta entram numa fila, senão duas leituras simultâneas se atropelam e a última
+ * gravação apaga a mudança da outra. `change` não pode chamar updateManual da mesma pasta (travaria).
+ */
+export declare function updateManual<T>(dir: string, change: (meta: ManualMeta) => T): Promise<T>;
+/** Roda `task` na fila da pasta (a mesma do updateManual). `task` não pode entrar na fila da mesma pasta de novo. */
+export declare function inQueue<T>(dir: string, task: () => Promise<T>): Promise<T>;

package/dist/core/manuals.js

@@ -0,0 +1,86 @@
+import { mkdir, readdir } from "node:fs/promises";
+import path from "node:path";
+import { atomicWrite, exists, readText, uniquePath } from "./fs.js";
+import { required, slugify } from "./text.js";
+import { FORMAT_VERSION } from "./types.js";
+const META_FILE = "manual.json";
+export const PAGES_DIR = "pages";
+export const ASSETS_DIR = "assets";
+export async function createManual(workspace, opts) {
+    const title = required(opts.title, "título do manual");
+    const dir = await uniquePath(workspace, slugify(title), "");
+    const meta = { version: FORMAT_VERSION, title, language: opts.language, pages: [] };
+    await mkdir(path.join(dir, PAGES_DIR), { recursive: true });
+    await mkdir(path.join(dir, ASSETS_DIR), { recursive: true });
+    await writeManual(dir, meta);
+    return { dir, meta };
+}
+/**
+ * Manuais são as subpastas diretas do workspace que têm manual.json.
+ * Manual com manual.json ilegível fica de fora da lista, para um manual estragado não impedir
+ * de abrir os outros. Abrir ele pelo endereço mostra o erro de readManual.
+ */
+export async function listManuals(workspace) {
+    const entries = await readdir(workspace, { withFileTypes: true });
+    const manuals = [];
+    for (const e of entries) {
+        if (!e.isDirectory())
+            continue;
+        const dir = path.join(workspace, e.name);
+        if (!(await exists(path.join(dir, META_FILE))))
+            continue;
+        try {
+            manuals.push({ dir, meta: await readManual(dir) });
+        }
+        catch {
+            // manual.json corrompido: os outros manuais continuam abrindo.
+        }
+    }
+    return manuals.sort((a, b) => a.meta.title.localeCompare(b.meta.title));
+}
+export async function readManual(dir) {
+    let meta;
+    try {
+        meta = JSON.parse(await readText(path.join(dir, META_FILE)));
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            throw new Error(`O ${META_FILE} do manual "${path.basename(dir)}" não é um JSON válido: ${err.message}`);
+        throw err;
+    }
+    if (meta?.version !== FORMAT_VERSION) {
+        throw new Error(`${META_FILE}: versão de formato não suportada (${String(meta?.version)})`);
+    }
+    return meta;
+}
+export async function writeManual(dir, meta) {
+    await atomicWrite(path.join(dir, META_FILE), `${JSON.stringify(meta, null, 2)}\n`);
+}
+const queues = new Map();
+/**
+ * Lê o manual, aplica a mudança e grava de volta. Concentra o ciclo ler-alterar-gravar da árvore.
+ * Chamadas da mesma pasta entram numa fila, senão duas leituras simultâneas se atropelam e a última
+ * gravação apaga a mudança da outra. `change` não pode chamar updateManual da mesma pasta (travaria).
+ */
+export function updateManual(dir, change) {
+    return inQueue(dir, async () => {
+        const meta = await readManual(dir);
+        const result = change(meta);
+        await writeManual(dir, meta);
+        return result;
+    });
+}
+/** Roda `task` na fila da pasta (a mesma do updateManual). `task` não pode entrar na fila da mesma pasta de novo. */
+export function inQueue(dir, task) {
+    const key = path.resolve(dir);
+    const run = (queues.get(key) ?? Promise.resolve()).catch(() => { }).then(task);
+    queues.set(key, run);
+    // Fila vazia: tira a pasta do Map. Falha já chega a quem chamou por `run`.
+    const clean = () => {
+        if (queues.get(key) === run)
+            queues.delete(key);
+    };
+    run.then(clean, clean);
+    return run;
+}
+//# sourceMappingURL=manuals.js.map

package/dist/core/pages.d.ts

@@ -0,0 +1,43 @@
+import { type Page, type PageStatus } from "./types.js";
+/** Página pode ficar sem título enquanto é escrita: a árvore mostra "Sem título" e o arquivo vira sem-titulo.md. */
+export declare function addPage(dir: string, opts: {
+    title: string;
+    body?: string;
+    parentId?: string | null;
+    index?: number;
+}): Promise<Page>;
+export declare function readPage(dir: string, id: string): Promise<Page>;
+export interface PageTreeNode {
+    id: string;
+    title: string;
+    status: PageStatus;
+    file: string;
+    /** Preenchido quando o arquivo da página sumiu ou está com erro: a página aparece, com o aviso. */
+    problem?: string;
+    /** Versão escolhida para o manual final, quando há uma (ver versions.ts). */
+    published?: string;
+    children: PageTreeNode[];
+}
+/**
+ * Árvore do manual com o título de cada página (que fica no frontmatter). Lê o manual.json uma vez.
+ * Uma página com problema não derruba a árvore: ela vem com `problem` e o resto continua.
+ */
+export declare function readPageTree(dir: string): Promise<PageTreeNode[]>;
+/**
+ * Quando o título muda, o arquivo é renomeado para acompanhar, para a pasta continuar legível
+ * para pessoas e IAs. O id no frontmatter não muda, e é ele que as áreas clicáveis usam.
+ * `fileName`: "keep" grava o título no mesmo arquivo (digitação em andamento); "sync" renomeia
+ * se o nome do arquivo não combina com o título (ao parar de digitar ou sair da página).
+ */
+export declare function updatePage(dir: string, id: string, patch: {
+    title?: string;
+    body?: string;
+    status?: PageStatus;
+}, opts?: {
+    fileName?: "keep" | "sync" | undefined;
+    ifMatch?: string | undefined;
+}): Promise<Page>;
+export declare function movePage(dir: string, id: string, to: {
+    parentId: string | null;
+    index: number;
+}): Promise<void>;

package/dist/core/pages.js

@@ -0,0 +1,179 @@
+import { randomUUID } from "node:crypto";
+import { rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { ExplicaiError } from "./errors.js";
+import { joinFrontmatter, splitFrontmatter } from "./frontmatter.js";
+import { atomicWrite, readText, relativePosix, resolveInside, uniquePath } from "./fs.js";
+import { inQueue, PAGES_DIR, readManual, updateManual } from "./manuals.js";
+import { slugify } from "./text.js";
+import { childrenOf, clampIndex, findIn, findNode, flatten } from "./tree.js";
+import { PAGE_STATUSES } from "./types.js";
+/** Página pode ficar sem título enquanto é escrita: a árvore mostra "Sem título" e o arquivo vira sem-titulo.md. */
+export async function addPage(dir, opts) {
+    const title = opts.title.trim();
+    const page = {
+        id: randomUUID(),
+        title,
+        status: "rascunho",
+        body: opts.body ?? "",
+        file: await newPageFile(dir, title),
+    };
+    // Arquivo primeiro: se gravar falhar, a árvore não aponta para o que não existe. Se a árvore falhar, desfaz o arquivo.
+    await writePageFile(dir, page);
+    page.version = await fileVersion(dir, page.file);
+    try {
+        await updateManual(dir, (meta) => {
+            const siblings = childrenOf(meta.pages, opts.parentId);
+            siblings.splice(clampIndex(opts.index, siblings.length), 0, { id: page.id, file: page.file, children: [] });
+        });
+    }
+    catch (err) {
+        await rm(resolveInside(dir, page.file), { force: true });
+        throw err;
+    }
+    return page;
+}
+export async function readPage(dir, id) {
+    const { node } = findNode((await readManual(dir)).pages, id);
+    return { id, ...(await readPageFile(dir, node.file)), file: node.file, version: await fileVersion(dir, node.file) };
+}
+/** Versão do arquivo: mtime + tamanho. Basta para saber se alguém mexeu nele desde a última leitura. */
+async function fileVersion(dir, file) {
+    const s = await stat(resolveInside(dir, file));
+    return `${s.mtimeMs}-${s.size}`;
+}
+/** Dentro da fila da pasta: recusa a gravação se o arquivo mudou no disco depois de `expected`. */
+async function assertVersion(dir, file, expected) {
+    if ((await fileVersion(dir, file)) === expected)
+        return;
+    throw new ExplicaiError("disk-conflict", "Esta página foi alterada fora do Studio depois que você a abriu. Recarregue do disco ou mantenha a sua versão.");
+}
+/**
+ * Árvore do manual com o título de cada página (que fica no frontmatter). Lê o manual.json uma vez.
+ * Uma página com problema não derruba a árvore: ela vem com `problem` e o resto continua.
+ */
+export async function readPageTree(dir) {
+    const walk = (nodes) => Promise.all(nodes.map(async (n) => {
+        const base = {
+            id: n.id,
+            file: n.file,
+            ...(n.published ? { published: n.published } : {}),
+            children: await walk(n.children),
+        };
+        try {
+            const { title, status } = await readPageFile(dir, n.file);
+            return { ...base, title, status };
+        }
+        catch (err) {
+            return { ...base, title: "", status: "rascunho", problem: err instanceof Error ? err.message : String(err) };
+        }
+    }));
+    return walk((await readManual(dir)).pages);
+}
+/** Lê título e corpo de um arquivo de página, com mensagem clara quando ele foi apagado ou estragado. */
+async function readPageFile(dir, file) {
+    let text;
+    try {
+        text = await readText(resolveInside(dir, file));
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new Error(`O arquivo ${file} não foi encontrado. Ele foi apagado ou renomeado fora do Studio.`);
+        }
+        throw err;
+    }
+    try {
+        const { data, body } = splitFrontmatter(text);
+        const status = PAGE_STATUSES.includes(data.status) ? data.status : "rascunho";
+        return { title: typeof data.title === "string" ? data.title : "", status, body };
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message.split("\n")[0] : String(err);
+        throw new Error(`O cabeçalho (frontmatter) de ${file} tem um erro: ${detail}`);
+    }
+}
+/**
+ * Quando o título muda, o arquivo é renomeado para acompanhar, para a pasta continuar legível
+ * para pessoas e IAs. O id no frontmatter não muda, e é ele que as áreas clicáveis usam.
+ * `fileName`: "keep" grava o título no mesmo arquivo (digitação em andamento); "sync" renomeia
+ * se o nome do arquivo não combina com o título (ao parar de digitar ou sair da página).
+ */
+export async function updatePage(dir, id, patch, opts = {}) {
+    const page = await readPage(dir, id);
+    if (patch.status !== undefined && !PAGE_STATUSES.includes(patch.status)) {
+        throw new Error(`Status inválido: ${patch.status}. Use ${PAGE_STATUSES.join(", ")}.`);
+    }
+    const next = {
+        ...page,
+        ...(patch.status === undefined ? {} : { status: patch.status }),
+        ...(patch.title === undefined ? {} : { title: patch.title.trim() }),
+        ...(patch.body === undefined ? {} : { body: patch.body }),
+    };
+    const sameName = opts.fileName === "keep" ||
+        (opts.fileName === "sync" ? fileMatchesTitle(page.file, next.title) : slugify(next.title) === slugify(page.title));
+    const { ifMatch } = opts;
+    if (sameName) {
+        if (ifMatch === undefined)
+            await writePageFile(dir, next);
+        else {
+            await inQueue(dir, async () => {
+                await assertVersion(dir, page.file, ifMatch);
+                await writePageFile(dir, next);
+            });
+        }
+        return { ...next, version: await fileVersion(dir, next.file) };
+    }
+    // shortcut: com renomeio, a checagem e a gravação não são atômicas (janela de milissegundos); upgrade se aparecer na prática.
+    if (ifMatch !== undefined)
+        await inQueue(dir, () => assertVersion(dir, page.file, ifMatch));
+    next.file = await newPageFile(dir, next.title);
+    await writePageFile(dir, next);
+    const others = await updateManual(dir, (meta) => {
+        findNode(meta.pages, id).node.file = next.file;
+        return flatten(meta.pages).filter((n) => n.id !== id);
+    });
+    await rm(resolveInside(dir, page.file), { force: true });
+    await relink(dir, others.map((n) => n.file), page.file, next.file);
+    return { ...next, version: await fileVersion(dir, next.file) };
+}
+/** O arquivo já tem o nome do título: `titulo.md` ou `titulo-2.md` (sufixo que `uniquePath` põe). */
+function fileMatchesTitle(file, title) {
+    const base = path.posix.basename(file, ".md");
+    const want = slugify(title);
+    return base === want || (base.startsWith(`${want}-`) && /^\d+$/.test(base.slice(want.length + 1)));
+}
+/** Links entre páginas são `./arquivo.md`. Quando um arquivo muda de nome, as outras páginas acompanham. */
+async function relink(dir, files, from, to) {
+    const name = (f) => path.posix.basename(f);
+    const escaped = name(from).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    // ](arquivo.md  ou  ](./arquivo.md  seguido de ) ou de #âncora
+    // Precisa ser new RegExp: o nome do arquivo entra no padrão (teste: "atualiza os links das outras páginas")
+    const pattern = new RegExp(`(\\]\\()(?:\\./)?${escaped}(?=[)#])`, "g");
+    for (const file of files) {
+        const abs = resolveInside(dir, file);
+        const text = await readText(abs);
+        const updated = text.replace(pattern, `$1./${name(to)}`);
+        if (updated !== text)
+            await atomicWrite(abs, updated);
+    }
+}
+export async function movePage(dir, id, to) {
+    await updateManual(dir, (meta) => {
+        const { node, siblings } = findNode(meta.pages, id);
+        if (to.parentId && (to.parentId === id || findIn(node.children, to.parentId))) {
+            throw new Error("Não dá para mover uma página para dentro dela mesma.");
+        }
+        siblings.splice(siblings.indexOf(node), 1);
+        const target = childrenOf(meta.pages, to.parentId);
+        target.splice(clampIndex(to.index, target.length), 0, node);
+    });
+}
+async function newPageFile(dir, title) {
+    return relativePosix(dir, await uniquePath(path.join(dir, PAGES_DIR), slugify(title), ".md"));
+}
+async function writePageFile(dir, page) {
+    // Rascunho é o padrão e não vai para o arquivo: página escrita à mão continua igual.
+    const status = page.status === "rascunho" ? {} : { status: page.status };
+    await atomicWrite(resolveInside(dir, page.file), joinFrontmatter({ id: page.id, title: page.title, ...status }, page.body));
+}
+//# sourceMappingURL=pages.js.map

package/dist/core/redact.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Troca o arquivo de `assets/` pela versão com as tarjas já queimadas (o navegador desenha e envia).
+ * Valida o formato e que a imagem abre, grava num temporário e renomeia por cima do caminho de sempre,
+ * então Markdown e marcações seguem valendo. O original não vai para a lixeira: some, junto com
+ * qualquer cópia idêntica dele na pasta de imagens sem uso.
+ */
+export declare function redactAsset(dir: string, assetPath: string, data: Uint8Array): Promise<void>;
+/** A pasta do manual está dentro de um repositório git? Procura `.git` na pasta e nas de cima. */
+export declare function insideGitRepo(dir: string): Promise<boolean>;