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

package/dist/files/paths.js

@@ -0,0 +1,144 @@
+import { lstat, realpath } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { errnoCode, HttpError } from "../server/http.js";
+/**
+ * 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 const RESERVED_ROOT_DIR = '.pix3';
+/**
+ * Entries directly under `.pix3/` that belong to the plugin (compared case-insensitively, so a
+ * case-insensitive disk cannot be used to spell them differently). Anything below a private
+ * directory is private too.
+ */
+const PLUGIN_PRIVATE_ENTRIES = new Set([
+    'dev.json',
+    'dev.log',
+    'tmp',
+    'tx',
+    'history',
+    'local',
+]);
+/**
+ * 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 const isPluginPrivatePath = (wirePath) => {
+    const segments = wirePath.split('/');
+    if (segments[0].toLowerCase() !== RESERVED_ROOT_DIR)
+        return false;
+    if (segments.length === 1)
+        return true;
+    return PLUGIN_PRIVATE_ENTRIES.has(segments[1].toLowerCase());
+};
+const MAX_PATH_LENGTH = 4096;
+const bad = (message) => new HttpError(400, 'bad_path', message);
+/** Validate a wire path and return it unchanged (it is already canonical when accepted). */
+export const parseWirePath = (raw, field = 'path') => {
+    if (typeof raw !== 'string' || raw.length === 0)
+        throw bad(`\`${field}\` must be a non-empty string.`);
+    if (raw.length > MAX_PATH_LENGTH)
+        throw bad(`\`${field}\` is too long.`);
+    if (raw.includes('\0'))
+        throw bad(`\`${field}\` contains a NUL byte.`);
+    if (raw.includes('\\'))
+        throw bad(`\`${field}\` must use "/" separators, not backslashes.`);
+    if (raw.startsWith('/'))
+        throw bad(`\`${field}\` must be relative to the project root.`);
+    if (/^[A-Za-z]:/.test(raw))
+        throw bad(`\`${field}\` must not carry a drive letter.`);
+    for (const segment of raw.split('/')) {
+        if (segment === '')
+            throw bad(`\`${field}\` has an empty segment (leading, trailing or double "/").`);
+        if (segment === '.' || segment === '..')
+            throw bad(`\`${field}\` must not contain "." or "..".`);
+        // Windows spellings of ANOTHER name, refused on every platform so a path means the same thing
+        // everywhere: `name:stream` is an NTFS alternate data stream, and Win32 strips trailing dots
+        // and spaces (`dev.json.` opens `dev.json`).
+        if (segment.includes(':'))
+            throw bad(`\`${field}\` must not contain ":" (a drive or an NTFS stream name).`);
+        if (segment.endsWith('.') || segment.endsWith(' '))
+            throw bad(`\`${field}\` has a segment ending in "." or a space.`);
+    }
+    if (isPluginPrivatePath(raw)) {
+        throw new HttpError(403, 'reserved_path', `\`${RESERVED_ROOT_DIR}\` itself and \`${RESERVED_ROOT_DIR}/{dev.json,dev.log,tmp,tx,history,` +
+            'local}` belong to the plugin.');
+    }
+    return raw;
+};
+/**
+ * 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 const resolveInsideRoot = async (root, wirePath, options) => {
+    const segments = wirePath.split('/');
+    let current = root;
+    for (let i = 0; i < segments.length; i++) {
+        current = join(current, segments[i]);
+        const last = i === segments.length - 1;
+        let stats;
+        try {
+            stats = await lstat(current);
+        }
+        catch (error) {
+            const code = errnoCode(error);
+            if (code === 'ENOENT') {
+                if (!options.allowMissing)
+                    throw new HttpError(404, 'not_found', `${wirePath} does not exist.`);
+                return { absolute: join(root, ...segments), kind: null };
+            }
+            if (code === 'ENOTDIR') {
+                throw new HttpError(409, 'not_a_directory', `A parent of ${wirePath} is not a directory.`);
+            }
+            throw error;
+        }
+        if (stats.isSymbolicLink()) {
+            throw new HttpError(403, 'symlink', `${wirePath} goes through a symbolic link; the file API does not follow them.`);
+        }
+        if (!last && !stats.isDirectory()) {
+            throw new HttpError(409, 'not_a_directory', `A parent of ${wirePath} is not a directory.`);
+        }
+        if (process.platform === 'win32') {
+            await refuseShortNameAlias(current, segments[i], wirePath);
+        }
+        if (last) {
+            return {
+                absolute: current,
+                kind: stats.isFile() ? 'file' : stats.isDirectory() ? 'dir' : 'other',
+            };
+        }
+    }
+    // Unreachable: `parseWirePath` guarantees at least one segment.
+    throw bad('Empty path.');
+};
+/**
+ * Windows only: refuse a segment that opened the entry under a name other than its own — an 8.3
+ * short name (`.pix3/DEV~1.JSO`) would otherwise slip past {@link isPluginPrivatePath}, which only
+ * knows the long names. NTFS names are case-insensitive, and case is not an alias.
+ */
+const refuseShortNameAlias = async (absolute, segment, wirePath) => {
+    const longName = basename(await realpath(absolute));
+    if (longName.toLowerCase() !== segment.toLowerCase()) {
+        throw bad(`${wirePath} uses "${segment}", an alias of "${longName}"; use the long name.`);
+    }
+};
+/** Parent wire path, or `null` for a top-level entry. */
+export const parentOf = (wirePath) => {
+    const slash = wirePath.lastIndexOf('/');
+    return slash < 0 ? null : wirePath.slice(0, slash);
+};

package/dist/files/project-files.d.ts

@@ -0,0 +1,208 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type ChangesetEntry } from './changeset.ts';
+import { VersionJournal, type HistoryEntry } from './history.ts';
+import { type ChangeEvent } from './scan.ts';
+/**
+ * The project's files as the editor sees them (plan §B.1, port of the file half of
+ * `packages/cli/src/serve/workspace-server.ts`): a table of every file in the revision set with
+ * its sha256, conditional atomic writes, mkdir/delete/move, batch hashing, and the change events
+ * the editor tab receives over `/__pix3/ws`.
+ *
+ * Every table mutation — own writes, watcher batches, scans, the writer hand-over — runs one at a
+ * time through {@link serial}; that queue is the mutex plan §C.3/§C.4 put the write path under.
+ */
+export type ChangeAuthor = 'editor' | 'external';
+export interface FsEvent extends ChangeEvent {
+    /** `editor` when the bytes are the plugin's last write of that path, else `external`. */
+    readonly author: ChangeAuthor;
+}
+/** One `pix3:fs` frame: every change of one batch, under one `seq`. */
+export interface FsFrame {
+    readonly type: 'pix3:fs';
+    readonly seq: number;
+    readonly revision: string;
+    readonly events: readonly FsEvent[];
+    /** The writer tab that made an `editor` batch through the API. */
+    readonly writerId?: string;
+}
+export interface ProjectFilesOptions {
+    /** Absolute project root (Vite's `root`). */
+    readonly root: string;
+    readonly log?: (line: string) => void;
+    /** Called for every batch of changes, own writes included. */
+    readonly onChange?: (frame: FsFrame) => void;
+    /** Quiet time after the last watch event before a batch is scanned (plan §B.1: 300 ms). */
+    readonly stabilityMs?: number;
+    /** Clock of the version journal (retention specs). */
+    readonly now?: () => number;
+    /**
+     * Test-only fault injection into a changeset. `afterRename(n)` runs after entry n was renamed
+     * into place: throwing makes the changeset fail (and roll back), resolving `'kill'` stops it dead
+     * — nothing more is renamed or cleaned up, as if the process died — for the recovery specs.
+     */
+    readonly faults?: {
+        readonly afterRename?: (index: number) => void | 'kill' | Promise<void | 'kill'>;
+    };
+}
+/** The answer of a changeset (`HostChangesetResult`). */
+export interface ChangesetResult {
+    readonly seq: number;
+    readonly files: readonly {
+        path: string;
+        sha256: string;
+        size: number;
+        seq: number;
+    }[];
+}
+export declare const STABILITY_INTERVAL_MS = 300;
+export declare class ProjectFiles {
+    readonly root: string;
+    private readonly log;
+    private readonly onChange;
+    private readonly stabilityMs;
+    private readonly cache;
+    private readonly table;
+    private readonly journal;
+    /** sha256 of the plugin's last write per path — what makes a change `author: 'editor'`. */
+    private readonly ownWrites;
+    private seq;
+    private revisionMemo;
+    private serialTail;
+    private dirty;
+    private batchTimer;
+    private firstDirtyAt;
+    private writer;
+    private closed;
+    private readonly faults;
+    /** The version journal `.pix3/history/` (plan §C.4). */
+    readonly history: VersionJournal;
+    constructor(options: ProjectFilesOptions);
+    get currentSeq(): number;
+    get writerId(): string | null;
+    /** sha256 over the sorted `path:sha256` lines of every file (see `computeRevision`). */
+    revision(): string;
+    /** sha256 of a file in the table, or null. */
+    hashOf(wirePath: string): string | null;
+    /** Every file of the revision set with its sha256. */
+    hashes(): Record<string, string>;
+    /**
+     * Recover interrupted changesets (plan §C.4) before the first scan, so the table never sees a
+     * half-applied transaction; then journal every journaled file whose bytes the journal does not
+     * have as its newest version (`external`: an agent or an IDE changed it while no dev server
+     * ran), so the version before the next change always exists.
+     */
+    start(): Promise<void>;
+    /**
+     * Journal what is on disk at `wirePath` now (if it is a journaled path). Never fails the caller:
+     * the write it follows already happened, and a lost journal entry is not a lost file.
+     */
+    private journalFile;
+    /** Journal the files of a batch the watcher or a rescan found (author as the frame says). */
+    private journalEvents;
+    close(): Promise<void>;
+    /**
+     * Every table mutation (own writes, watcher batches, scans) runs one at a time. Once closed,
+     * new work is refused (503): what was queued before `close()` still finishes, nothing after it
+     * can land behind the back of the next server's instance.
+     */
+    serial<T>(work: () => Promise<T>): Promise<T>;
+    private nextSeq;
+    private authored;
+    private emit;
+    /** A watch event for an absolute path (Vite's `server.watcher`); ignored outside the set. */
+    noteFsEvent(absolute: string): void;
+    private flushDirty;
+    /**
+     * Plan §B.1 stabilisation: scan, wait {@link stabilityMs}, scan again; a file whose hash differs
+     * between the two scans is still being written and stays out of this batch (its old entry is
+     * kept, and the caller retries it). Returns the unstable paths.
+     */
+    private stableRescan;
+    /**
+     * Full rescan now, without stabilisation (plan §B.3 step 1: the agent says it is done). Changes
+     * are broadcast like any batch and returned as `{path: sha256 | null}`.
+     */
+    rescanAll(): Promise<{
+        events: FsEvent[];
+        seq: number;
+    }>;
+    /**
+     * `POST /__pix3/api/handover/claim {writerId}` — under the write mutex, so a write the previous
+     * writer already had accepted completes first. Returns the disk the new writer starts from.
+     */
+    claim(raw: unknown): Promise<Record<string, unknown>>;
+    /** Mutations are taken only from the current writer (`X-Pix3-Writer`), once one has claimed. */
+    private checkWriter;
+    manifest(): Promise<Record<string, unknown>>;
+    hashPaths(body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** sha256 of what is on disk at `wirePath` now, or null (missing, a directory, unreachable). */
+    diskHash(wirePath: string): Promise<string | null>;
+    readFile(req: IncomingMessage, res: ServerResponse, url: URL, headOnly: boolean): Promise<void>;
+    private mutationId;
+    /**
+     * Run `work` at most once per mutation id in this dev-server session. A retry of an id already
+     * applied (or still in flight) gets the recorded answer and `X-Mutation-Replayed: true`, and
+     * `work` does not run again — the rule that keeps a lost response from deleting or moving twice.
+     * Reusing an id for a different request is refused (422), not silently replayed.
+     */
+    private journaled;
+    /**
+     * The file's sha256 now. `precondition: true` (an `If-Match` check before a write) hashes the
+     * bytes for real and refreshes the cache: the cache is keyed `ino:size:mtimeNs`, and an agent's
+     * same-size rewrite within one timestamp tick keeps the key — a stale sha would let the editor's
+     * write pass the check and overwrite the agent's bytes without a 412. Reads (an ETag) keep the
+     * cheap path.
+     */
+    private currentHashOf;
+    /**
+     * Record a write of the plugin in the table; the watcher's echo then finds nothing new. `own`
+     * false is a restore: the bytes are on disk because of the plugin, but no tab wrote them, so
+     * a later batch must not attribute them to the editor either.
+     */
+    private recordOwnFile;
+    /** Make sure every ancestor directory of `wirePath` that now exists is in the table. */
+    private recordAncestors;
+    writeFile(req: IncomingMessage, res: ServerResponse, url: URL): Promise<void>;
+    private performPut;
+    private streamBodyTo;
+    jsonMutation(req: IncomingMessage, res: ServerResponse, op: 'mkdir' | 'delete' | 'move', body: Record<string, unknown>): Promise<void>;
+    /** Rescan `prefixes` after an own mutation and broadcast the result as the writer's batch. */
+    private ownRescan;
+    private performMkdir;
+    /** The outermost ancestor (or the path itself) the table did not know — what an own write created. */
+    private topmostNew;
+    private performDelete;
+    private performMove;
+    /** `POST /__pix3/api/changeset` `{files: [{path, text? | base64?, ifMatch?, createOnly?}]}`. */
+    writeChangeset(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /**
+     * Several files as one transaction, under {@link serial} like every write and the hand-over: so
+     * a changeset accepted before a claim completes before the claim answers, and one arriving after
+     * it gets `409 writer_superseded` (plan §C.3 step 3). Preflight → stage → rename each →
+     * `committed` → table, journal, ONE `pix3:fs` frame. A failed rename rolls the renamed files back
+     * from `old/` before the error is answered; a crash is recovered at the next {@link start}.
+     */
+    performChangeset(entries: readonly ChangesetEntry[], writerId: string | null): Promise<ChangesetResult>;
+    /**
+     * Undo the renames of a failed changeset, newest first. If that fails too the transaction
+     * directory stays (still `prepared`), and recovery at the next start finishes the rollback.
+     */
+    private rollBack;
+    /** `GET /__pix3/api/history?path=` → `{entries}`, newest first. */
+    historyList(url: URL): Promise<Record<string, unknown>>;
+    /** `GET /__pix3/api/history/version?path=&id=` → the version's raw bytes. */
+    historyVersion(res: ServerResponse, url: URL, headOnly: boolean): Promise<void>;
+    /**
+     * `POST /__pix3/api/history/record {path, text, author: 'rejected-draft', note?}`. No writer
+     * check: a superseded tab is exactly the one that has to keep its draft (§C.3 step 3).
+     */
+    historyRecord(body: Record<string, unknown>): Promise<HistoryEntry>;
+    /** `POST /__pix3/api/history/restore {path, id}` (+ `If-Match`, `X-Mutation-Id`). */
+    historyRestore(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /**
+     * Write a journaled version back, like a PUT from the writer — but NOT as an own write: the
+     * frame says `external` and carries no writer, so the editor follows the disk (reload or §C.3
+     * merge) exactly as after an agent's change, instead of taking it for the echo of its flush.
+     */
+    private performRestore;
+}