@pix3/vite-plugin 0.0.0-stage → 2.0.0-alpha.1

package/dist/files/changeset.js

@@ -0,0 +1,321 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { chmod, copyFile, mkdir, open, readdir, readFile, rename, rm, unlink, } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { errnoCode, HttpError, isRecord } from "../server/http.js";
+import { parseWirePath, RESERVED_ROOT_DIR } from "./paths.js";
+export const MAX_CHANGESET_BYTES = 256 * 1024 * 1024;
+const MAX_CHANGESET_FILES = 1_000;
+export const txRootOf = (root) => join(root, RESERVED_ROOT_DIR, 'tx');
+const sha256Of = (bytes) => createHash('sha256').update(bytes).digest('hex');
+/** `"<hex>"`, `<hex>` or `*` from a JSON `ifMatch`. */
+const parseIfMatch = (raw, index) => {
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw !== 'string' || raw.trim() === '') {
+        throw new HttpError(400, 'bad_request', `files[${index}].ifMatch must be a string.`);
+    }
+    const tag = raw.trim().replace(/^W\//, '');
+    return [tag.startsWith('"') && tag.endsWith('"') && tag.length >= 2 ? tag.slice(1, -1) : tag];
+};
+/** Validate `POST /__pix3/api/changeset` `{files: [{path, text? | base64?, ifMatch?, createOnly?}]}`. */
+export const parseChangeset = (body) => {
+    const raw = body.files;
+    if (!Array.isArray(raw) || raw.length === 0) {
+        throw new HttpError(400, 'bad_request', '`files` must be a non-empty array.');
+    }
+    if (raw.length > MAX_CHANGESET_FILES) {
+        throw new HttpError(413, 'too_many_files', `At most ${MAX_CHANGESET_FILES} files.`);
+    }
+    const seen = new Set();
+    return raw.map((item, index) => {
+        if (!isRecord(item))
+            throw new HttpError(400, 'bad_request', `files[${index}] is not an object.`);
+        const path = parseWirePath(item.path, `files[${index}].path`);
+        if (seen.has(path)) {
+            throw new HttpError(400, 'bad_request', `${path} appears twice in one changeset.`);
+        }
+        seen.add(path);
+        const hasText = typeof item.text === 'string';
+        const hasBase64 = typeof item.base64 === 'string';
+        if (hasText === hasBase64) {
+            throw new HttpError(400, 'bad_request', `files[${index}] needs exactly one of \`text\` or \`base64\`.`);
+        }
+        const data = hasText
+            ? Buffer.from(item.text, 'utf8')
+            : Buffer.from(item.base64, 'base64');
+        return {
+            path,
+            data,
+            sha256: sha256Of(data),
+            ifMatch: parseIfMatch(item.ifMatch, index),
+            createOnly: item.createOnly === true,
+        };
+    });
+};
+/** A request fingerprint for `X-Mutation-Id` replay: same paths, conditions and bytes. */
+export const changesetFingerprint = (entries) => [
+    'changeset',
+    ...entries.map(entry => `${entry.path}\n${entry.sha256}\n${entry.ifMatch?.join(',') ?? ''}\n${entry.createOnly}`),
+].join('\n');
+/** fsync a directory, so a rename or a create inside it is durable. A no-op where unsupported. */
+export const fsyncDir = async (dir) => {
+    let handle;
+    try {
+        handle = await open(dir, 'r');
+        await handle.sync();
+    }
+    catch (error) {
+        // Windows cannot open a directory for fsync (EPERM/EISDIR); NTFS journals the rename itself.
+        const code = errnoCode(error);
+        if (code !== 'EPERM' && code !== 'EISDIR' && code !== 'EINVAL' && code !== 'EBADF')
+            throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+};
+/** Write `bytes` to a new file and fsync it. */
+const writeSynced = async (path, bytes) => {
+    const handle = await open(path, 'wx');
+    try {
+        await handle.writeFile(bytes);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+};
+/** Replace `intent.json` atomically and durably (temp + fsync + rename + fsync of the dir). */
+export const writeIntent = async (txDir, intent) => {
+    const temp = join(txDir, `intent.${randomBytes(4).toString('hex')}.tmp`);
+    await writeSynced(temp, Buffer.from(`${JSON.stringify(intent, null, 2)}\n`));
+    await rename(temp, join(txDir, 'intent.json'));
+    await fsyncDir(txDir);
+};
+/**
+ * Rename `temp` over `target`. When `.pix3/` is on another device than the target, the bytes are
+ * copied to a sibling first and renamed from there, so the replace itself stays atomic.
+ */
+export const renameIntoPlace = async (temp, target) => {
+    try {
+        await rename(temp, target);
+    }
+    catch (error) {
+        if (errnoCode(error) !== 'EXDEV')
+            throw error;
+        const sibling = join(dirname(target), `.${basename(target)}.pix3-tmp-${randomBytes(6).toString('hex')}`);
+        const source = await open(temp, 'r');
+        try {
+            await pipeline(source.createReadStream(), createWriteStream(sibling, { flags: 'wx' }));
+        }
+        finally {
+            await source.close().catch(() => undefined);
+        }
+        await rename(sibling, target);
+        await rm(temp, { force: true });
+    }
+};
+/**
+ * Steps 3 of plan §C.4: stage the new bytes and copies of the old ones, then write the intent
+ * (`prepared`). Returns the transaction directory and its intent; nothing in the project changed.
+ */
+export const stageTransaction = async (root, files) => {
+    const id = `${Date.now()}-${randomBytes(6).toString('hex')}`;
+    const txDir = join(txRootOf(root), id);
+    await mkdir(join(txDir, 'new'), { recursive: true, mode: 0o700 });
+    await mkdir(join(txDir, 'old'), { recursive: true, mode: 0o700 });
+    const intentFiles = [];
+    for (const [n, file] of files.entries()) {
+        const staged = join(txDir, 'new', String(n));
+        await writeSynced(staged, file.entry.data);
+        if (file.mode !== null) {
+            const handle = await open(staged, 'r');
+            try {
+                await handle.chmod(file.mode);
+            }
+            finally {
+                await handle.close();
+            }
+            const old = join(txDir, 'old', String(n));
+            await copyFile(file.absolute, old);
+            // Windows requires a writable handle for fsync. A copied read-only file must also be
+            // writable while opening it; restore its original mode on the handle before syncing.
+            await chmod(old, file.mode | 0o600);
+            const oldHandle = await open(old, 'r+');
+            try {
+                await oldHandle.chmod(file.mode);
+                await oldHandle.sync();
+            }
+            finally {
+                await oldHandle.close();
+            }
+        }
+        intentFiles.push({
+            path: file.entry.path,
+            sha256: file.entry.sha256,
+            old: file.mode === null ? 'absent' : `old/${n}`,
+        });
+    }
+    await fsyncDir(join(txDir, 'new'));
+    await fsyncDir(join(txDir, 'old'));
+    const intent = { id, files: intentFiles, state: 'prepared' };
+    await writeIntent(txDir, intent);
+    await fsyncDir(txRootOf(root));
+    return { txDir, intent };
+};
+/** Put entry `n`'s old bytes back (or remove the file it created). */
+export const rollBackFile = async (root, txDir, file) => {
+    const target = join(root, ...file.path.split('/'));
+    if (file.old === 'absent') {
+        await unlink(target).catch((error) => {
+            if (errnoCode(error) !== 'ENOENT')
+                throw error;
+        });
+        return;
+    }
+    await renameIntoPlace(join(txDir, file.old), target);
+};
+const hashFile = async (absolute) => {
+    try {
+        return sha256Of(await readFile(absolute));
+    }
+    catch (error) {
+        const code = errnoCode(error);
+        if (code === 'ENOENT' || code === 'ENOTDIR' || code === 'EISDIR')
+            return null;
+        throw error;
+    }
+};
+const exists = async (path) => {
+    try {
+        await open(path, 'r').then(handle => handle.close());
+        return true;
+    }
+    catch (error) {
+        if (errnoCode(error) === 'ENOENT')
+            return false;
+        throw error;
+    }
+};
+const isIntent = (value) => {
+    if (!isRecord(value))
+        return false;
+    if (typeof value.id !== 'string')
+        return false;
+    if (value.state !== 'prepared' && value.state !== 'committed')
+        return false;
+    if (!Array.isArray(value.files))
+        return false;
+    return value.files.every((file) => isRecord(file) &&
+        typeof file.path === 'string' &&
+        typeof file.sha256 === 'string' &&
+        (file.old === 'absent' || (typeof file.old === 'string' && /^old\/\d+$/.test(file.old))));
+};
+const readIntent = async (txDir) => {
+    try {
+        const parsed = JSON.parse(await readFile(join(txDir, 'intent.json'), 'utf8'));
+        if (!isIntent(parsed))
+            return null;
+        // A path in the intent is written to and deleted on recovery: it must be a valid wire path.
+        for (const file of parsed.files)
+            parseWirePath(file.path);
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Recovery at plugin start (plan §C.4), before the first scan. For every `.pix3/tx/<id>/`:
+ *
+ * - no readable intent → nothing was renamed yet (renames start after the intent is durable):
+ *   the directory is removed;
+ * - `committed` → every file is in place: clean up (the versions are journaled as `editor`);
+ * - `prepared` and consistent — every entry is either still staged with the intended bytes, or
+ *   gone from `new/` with the target at the intended sha → roll forward;
+ * - `prepared` and anything else (a staged file lost, a renamed target with other bytes) → roll
+ *   back every renamed entry from `old/` (a target whose old was `absent` is deleted).
+ *
+ * Either way both files of a two-file changeset end up all old or all new (gate row N6).
+ */
+export const recoverTransactions = async (root, log) => {
+    const txRoot = txRootOf(root);
+    let ids;
+    try {
+        ids = (await readdir(txRoot, { withFileTypes: true }))
+            .filter(entry => entry.isDirectory())
+            .map(entry => entry.name);
+    }
+    catch (error) {
+        if (errnoCode(error) === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const recovered = [];
+    for (const id of ids.sort()) {
+        const txDir = join(txRoot, id);
+        const intent = await readIntent(txDir);
+        if (!intent) {
+            log(`changeset ${id}: no readable intent, nothing was renamed; discarded`);
+            await rm(txDir, { recursive: true, force: true });
+            continue;
+        }
+        if (intent.state === 'committed') {
+            log(`changeset ${id}: committed; cleaned up`);
+            for (const file of intent.files)
+                recovered.push({ path: file.path, author: 'editor' });
+            await rm(txDir, { recursive: true, force: true });
+            continue;
+        }
+        const status = [];
+        for (const [n, file] of intent.files.entries()) {
+            const staged = join(txDir, 'new', String(n));
+            const target = join(root, ...file.path.split('/'));
+            if (await exists(staged)) {
+                status.push({
+                    file,
+                    staged,
+                    pending: true,
+                    consistent: (await hashFile(staged)) === file.sha256,
+                });
+            }
+            else {
+                status.push({
+                    file,
+                    staged,
+                    pending: false,
+                    consistent: (await hashFile(target)) === file.sha256,
+                });
+            }
+        }
+        if (status.every(item => item.consistent)) {
+            for (const item of status) {
+                const target = join(root, ...item.file.path.split('/'));
+                if (item.pending) {
+                    await mkdir(dirname(target), { recursive: true });
+                    await renameIntoPlace(item.staged, target);
+                }
+                recovered.push({ path: item.file.path, author: 'editor' });
+            }
+            log(`changeset ${id}: interrupted after staging; rolled forward (${intent.files.length} files)`);
+        }
+        else {
+            for (const item of status) {
+                // A still-staged entry never reached its target: the old bytes are what is there.
+                if (item.pending)
+                    continue;
+                if (item.file.old !== 'absent' && !(await exists(join(txDir, item.file.old)))) {
+                    log(`changeset ${id}: cannot roll back ${item.file.path}, its old copy is missing`);
+                    continue;
+                }
+                await rollBackFile(root, txDir, item.file);
+                recovered.push({ path: item.file.path, author: 'restore' });
+            }
+            log(`changeset ${id}: staging incomplete; rolled back (${intent.files.length} files)`);
+        }
+        await rm(txDir, { recursive: true, force: true });
+    }
+    return recovered;
+};

package/dist/files/content-type.d.ts

@@ -0,0 +1 @@
+export declare const contentTypeFor: (wirePath: string) => string;

package/dist/files/content-type.js

@@ -0,0 +1,56 @@
+/**
+ * `Content-Type` for `GET /__pix3/api/file`, by extension. The editor mostly turns bytes into Blobs and
+ * decides by path itself; the header matters for `<audio>`/`<video>` range playback and for
+ * anyone reading the route with curl. Unknown → `application/octet-stream`.
+ */
+const TYPES = {
+    pix3scene: 'text/yaml; charset=utf-8',
+    prefab: 'text/yaml; charset=utf-8',
+    pix3anim: 'text/yaml; charset=utf-8',
+    yaml: 'text/yaml; charset=utf-8',
+    yml: 'text/yaml; charset=utf-8',
+    json: 'application/json; charset=utf-8',
+    ts: 'text/plain; charset=utf-8',
+    tsx: 'text/plain; charset=utf-8',
+    js: 'text/javascript; charset=utf-8',
+    mjs: 'text/javascript; charset=utf-8',
+    md: 'text/markdown; charset=utf-8',
+    txt: 'text/plain; charset=utf-8',
+    csv: 'text/csv; charset=utf-8',
+    atlas: 'text/plain; charset=utf-8',
+    html: 'text/html; charset=utf-8',
+    css: 'text/css; charset=utf-8',
+    xml: 'application/xml; charset=utf-8',
+    svg: 'image/svg+xml',
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    avif: 'image/avif',
+    ktx2: 'image/ktx2',
+    mp3: 'audio/mpeg',
+    ogg: 'audio/ogg',
+    oga: 'audio/ogg',
+    wav: 'audio/wav',
+    m4a: 'audio/mp4',
+    aac: 'audio/aac',
+    flac: 'audio/flac',
+    mp4: 'video/mp4',
+    webm: 'video/webm',
+    mov: 'video/quicktime',
+    glb: 'model/gltf-binary',
+    gltf: 'model/gltf+json',
+    ttf: 'font/ttf',
+    otf: 'font/otf',
+    woff: 'font/woff',
+    woff2: 'font/woff2',
+    wasm: 'application/wasm',
+};
+export const contentTypeFor = (wirePath) => {
+    const name = wirePath.slice(wirePath.lastIndexOf('/') + 1);
+    const dot = name.lastIndexOf('.');
+    if (dot <= 0)
+        return 'application/octet-stream';
+    return TYPES[name.slice(dot + 1).toLowerCase()] ?? 'application/octet-stream';
+};

package/dist/files/history.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The version journal `.pix3/history/` (plan §C.4 "Журнал", Node port of the 1.x
+ * `RecoveryJournalService`). It is what the History panel lists and restores from, and what makes
+ * "the version before the agent's change" recoverable: every version a write, the watcher, a
+ * restore or a rejected editor draft produced is kept as raw bytes.
+ *
+ * Layout, per wire path `<p>` (the path's own segments, so `scenes/a.pix3scene` is a directory):
+ *
+ *     .pix3/history/<p>/index.jsonl          one JSON line per version, oldest first
+ *     .pix3/history/<p>/<stamp>-<hash8>      the version's bytes
+ *
+ * `<stamp>` is the epoch-ms time zero-padded to 13 digits (ids sort like their times), `<hash8>`
+ * the first 8 hex digits of the sha256. Every caller runs under `ProjectFiles.serial`, so appends
+ * and prunes of one index never interleave; readers skip a torn last line.
+ */
+export type HistoryAuthor = 'editor' | 'external' | 'restore' | 'rejected-draft';
+export interface HistoryEntry {
+    readonly id: string;
+    readonly path: string;
+    readonly author: HistoryAuthor;
+    readonly at: number;
+    readonly sha256: string;
+    readonly size: number;
+    readonly note?: string;
+}
+/**
+ * Retention per path (plan §C.4): the newest 200 versions, none older than 7 days — except the
+ * newest version, which age never prunes (the current disk must stay restorable).
+ */
+export declare const HISTORY_MAX_VERSIONS = 200;
+export declare const HISTORY_MAX_AGE_MS: number;
+/**
+ * Only scene-format files, locale tables (`locales/<id>.json`, written by the editor's
+ * Localization panel with the same merge) and the project file are journaled (plan §C.4: the
+ * History panel).
+ */
+export declare const isJournaledPath: (wirePath: string) => boolean;
+export interface VersionJournalOptions {
+    readonly root: string;
+    readonly log?: (line: string) => void;
+    /** Clock, for retention specs. */
+    readonly now?: () => number;
+}
+export declare class VersionJournal {
+    private readonly dir;
+    private readonly log;
+    private readonly now;
+    constructor(options: VersionJournalOptions);
+    private pathDir;
+    /** Every readable entry of `wirePath`, oldest first. */
+    private entries;
+    /** Newest first. */
+    list(wirePath: string): Promise<HistoryEntry[]>;
+    newest(wirePath: string): Promise<HistoryEntry | null>;
+    /** The bytes of version `id`, or null when the journal does not know it. */
+    read(wirePath: string, id: string): Promise<Buffer | null>;
+    /**
+     * Journal `bytes` as the newest version of `wirePath`. A version equal to the newest one is not
+     * recorded again (the watcher's echo of an own write, a restart over an unchanged disk): the
+     * newest entry is returned instead.
+     */
+    record(wirePath: string, bytes: Uint8Array, author: HistoryAuthor, note?: string): Promise<HistoryEntry>;
+    /** Drop what is beyond the newest {@link HISTORY_MAX_VERSIONS} or older than the age limit. */
+    private prune;
+}
+/** `author` of a `POST history/record` body: only the editor's own kind may be posted. */
+export declare const parseRecordAuthor: (raw: unknown) => "rejected-draft";

package/dist/files/history.js

@@ -0,0 +1,162 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { appendFile, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { errnoCode, HttpError } from "../server/http.js";
+import { RESERVED_ROOT_DIR } from "./paths.js";
+/**
+ * Retention per path (plan §C.4): the newest 200 versions, none older than 7 days — except the
+ * newest version, which age never prunes (the current disk must stay restorable).
+ */
+export const HISTORY_MAX_VERSIONS = 200;
+export const HISTORY_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const AUTHORS = new Set(['editor', 'external', 'restore', 'rejected-draft']);
+const ID_PATTERN = /^\d{13}-[0-9a-f]{8}(?:-\d{1,4})?$/;
+const INDEX = 'index.jsonl';
+/**
+ * Only scene-format files, locale tables (`locales/<id>.json`, written by the editor's
+ * Localization panel with the same merge) and the project file are journaled (plan §C.4: the
+ * History panel).
+ */
+export const isJournaledPath = (wirePath) => wirePath === 'pix3project.yaml' ||
+    wirePath.endsWith('.pix3scene') ||
+    wirePath.endsWith('.prefab') ||
+    /(?:^|\/)locales\/[^/]+\.json$/.test(wirePath);
+const isEntry = (value) => {
+    if (!value || typeof value !== 'object')
+        return false;
+    const entry = value;
+    return (typeof entry.id === 'string' &&
+        ID_PATTERN.test(entry.id) &&
+        typeof entry.path === 'string' &&
+        typeof entry.author === 'string' &&
+        AUTHORS.has(entry.author) &&
+        typeof entry.at === 'number' &&
+        typeof entry.sha256 === 'string' &&
+        typeof entry.size === 'number' &&
+        (entry.note === undefined || typeof entry.note === 'string'));
+};
+export class VersionJournal {
+    dir;
+    log;
+    now;
+    constructor(options) {
+        this.dir = join(options.root, RESERVED_ROOT_DIR, 'history');
+        this.log = options.log ?? (() => undefined);
+        this.now = options.now ?? Date.now;
+    }
+    pathDir(wirePath) {
+        return join(this.dir, ...wirePath.split('/'));
+    }
+    /** Every readable entry of `wirePath`, oldest first. */
+    async entries(wirePath) {
+        let raw;
+        try {
+            raw = await readFile(join(this.pathDir(wirePath), INDEX), 'utf8');
+        }
+        catch (error) {
+            if (errnoCode(error) === 'ENOENT' || errnoCode(error) === 'ENOTDIR')
+                return [];
+            throw error;
+        }
+        const out = [];
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (isEntry(parsed))
+                    out.push(parsed);
+            }
+            catch {
+                // a torn line from a crash mid-append; the version it described is simply not listed
+            }
+        }
+        return out;
+    }
+    /** Newest first. */
+    async list(wirePath) {
+        return (await this.entries(wirePath)).reverse();
+    }
+    async newest(wirePath) {
+        const all = await this.entries(wirePath);
+        return all.length > 0 ? all[all.length - 1] : null;
+    }
+    /** The bytes of version `id`, or null when the journal does not know it. */
+    async read(wirePath, id) {
+        if (!ID_PATTERN.test(id))
+            return null;
+        if (!(await this.entries(wirePath)).some(entry => entry.id === id))
+            return null;
+        try {
+            return await readFile(join(this.pathDir(wirePath), id));
+        }
+        catch (error) {
+            if (errnoCode(error) === 'ENOENT')
+                return null;
+            throw error;
+        }
+    }
+    /**
+     * Journal `bytes` as the newest version of `wirePath`. A version equal to the newest one is not
+     * recorded again (the watcher's echo of an own write, a restart over an unchanged disk): the
+     * newest entry is returned instead.
+     */
+    async record(wirePath, bytes, author, note) {
+        const sha256 = createHash('sha256').update(bytes).digest('hex');
+        const all = await this.entries(wirePath);
+        const last = all.length > 0 ? all[all.length - 1] : null;
+        if (last && last.sha256 === sha256)
+            return last;
+        const at = this.now();
+        const base = `${String(at).padStart(13, '0')}-${sha256.slice(0, 8)}`;
+        // A, B, A within one millisecond would reuse an id; ids are unique per path.
+        let id = base;
+        for (let n = 1; all.some(entry => entry.id === id); n++)
+            id = `${base}-${n}`;
+        const dir = this.pathDir(wirePath);
+        await mkdir(dir, { recursive: true });
+        await writeFile(join(dir, id), bytes);
+        const entry = {
+            id,
+            path: wirePath,
+            author,
+            at,
+            sha256,
+            size: bytes.byteLength,
+            ...(note ? { note } : {}),
+        };
+        await appendFile(join(dir, INDEX), `${JSON.stringify(entry)}\n`);
+        await this.prune(wirePath, [...all, entry]);
+        return entry;
+    }
+    /** Drop what is beyond the newest {@link HISTORY_MAX_VERSIONS} or older than the age limit. */
+    async prune(wirePath, all) {
+        const now = this.now();
+        const keep = [];
+        const drop = [];
+        all.forEach((entry, index) => {
+            const fromNewest = all.length - 1 - index;
+            const tooMany = fromNewest >= HISTORY_MAX_VERSIONS;
+            const tooOld = fromNewest > 0 && now - entry.at > HISTORY_MAX_AGE_MS;
+            (tooMany || tooOld ? drop : keep).push(entry);
+        });
+        if (drop.length === 0)
+            return;
+        const dir = this.pathDir(wirePath);
+        // Rewrite the index first (atomically), then delete the bytes: a crash in between leaves
+        // unlisted files, never a listed version without bytes.
+        const temp = join(dir, `${INDEX}.${randomBytes(6).toString('hex')}.tmp`);
+        await writeFile(temp, keep.map(entry => `${JSON.stringify(entry)}\n`).join(''));
+        await rename(temp, join(dir, INDEX));
+        for (const entry of drop)
+            await rm(join(dir, entry.id), { force: true });
+        this.log(`history: pruned ${drop.length} version(s) of ${wirePath}`);
+    }
+}
+/** `author` of a `POST history/record` body: only the editor's own kind may be posted. */
+export const parseRecordAuthor = (raw) => {
+    if (raw !== 'rejected-draft') {
+        throw new HttpError(400, 'bad_author', "Only `author: 'rejected-draft'` can be recorded.");
+    }
+    return raw;
+};

package/dist/files/paths.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Wire paths of the file API (port of `packages/cli/src/serve/paths.ts`): POSIX, relative to the
+ * project root (Vite's `root`), case preserved.
+ *
+ * The plugin enforces the root, so the rules are strict rather than normalising: a path that is
+ * not already canonical is refused, not repaired. Percent-decoding happens exactly once, by
+ * `URLSearchParams` for `?path=` (JSON bodies are not decoded at all) — a literal `%2e%2e` that
+ * survives that one decoding is an ordinary file name, never a second chance to spell `..`.
+ */
+/**
+ * Directory under the root that holds the plugin's own state (`dev.json`, staging, the version
+ * journal). Never part of the revision set; through the API only its plugin-private entries are
+ * refused, so the editor can still keep its own files there.
+ */
+export declare const RESERVED_ROOT_DIR = ".pix3";
+/**
+ * True for paths the file API refuses with `403 reserved_path`: `.pix3` itself (so it can be
+ * neither deleted nor moved) and the plugin-private entries under it.
+ */
+export declare const isPluginPrivatePath: (wirePath: string) => boolean;
+/** Validate a wire path and return it unchanged (it is already canonical when accepted). */
+export declare const parseWirePath: (raw: unknown, field?: string) => string;
+export interface ResolvedPath {
+    readonly absolute: string;
+    /** What is at the path now; `null` when nothing is (only possible with `allowMissing`). */
+    readonly kind: 'file' | 'dir' | 'other' | null;
+}
+/**
+ * Resolve a validated wire path under `root` without ever passing through a symlink.
+ *
+ * Every existing component (parents included, which is what protects a path about to be CREATED)
+ * is `lstat`ed: a symlink anywhere is refused with 403 `symlink`, a file where a directory is
+ * needed with 409 `not_a_directory`. This is a check, not a lock: a local process that swaps a
+ * directory for a symlink between the check and the use wins the race (same-user local processes
+ * are trusted).
+ */
+export declare const resolveInsideRoot: (root: string, wirePath: string, options: {
+    readonly allowMissing: boolean;
+}) => Promise<ResolvedPath>;
+/** Parent wire path, or `null` for a top-level entry. */
+export declare const parentOf: (wirePath: string) => string | null;