@young1lin/dsh-ui-gitworkbench 0.1.4 → 0.1.6

package/lib/fs-remove.js

@@ -0,0 +1,73 @@
+/**
+ * The one filesystem delete in this plugin, and the checks it carries.
+ *
+ * `discard-ops.ts` plans a delete when git has no copy of a file to restore
+ * from — untracked, or added-but-never-committed. git will not carry that out:
+ * `git clean` refuses paths it cannot index, which on Windows includes every
+ * reserved device name (`nul`, `con`, `aux`, `com1`, and the same names with
+ * any extension). So the removal goes through the filesystem, where git's own
+ * refusal to leave the repository does not apply — hence the checks here
+ * rather than a bare `rm`.
+ *
+ * Lives outside `index.ts` so vitest can load it: the class there needs the
+ * dsh runtime, and the property worth testing is "what does this delete, and
+ * what does it refuse" — a question about paths and the disk, not about RPC.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/fs-remove
+ */
+import { rm } from 'node:fs/promises';
+import { resolve, sep } from 'node:path';
+import { isSafeRelativePath } from './discard-ops.js';
+/**
+ * Resolve a repo-relative path against the worktree root, refusing to leave it.
+ *
+ * The second lock rather than the only one: {@link isSafeRelativePath} already
+ * rejected traversal spellings when the plan was made. This re-checks the
+ * RESOLVED path, which is the form the filesystem acts on, so a path that
+ * survives the first check by being spelled unusually still has to land inside
+ * the root to be acted on.
+ *
+ * @param root - the worktree directory, absolute.
+ * @param relative - repo-relative path from a plan step.
+ * @returns the absolute path to act on.
+ * @throws if the path is not a safe relative path, resolves outside the root,
+ *         or IS the root.
+ */
+export function resolveInside(root, relative) {
+    if (!isSafeRelativePath(relative)) {
+        throw new Error(`unsafe path to delete: ${JSON.stringify(relative)}`);
+    }
+    const base = resolve(root);
+    const target = resolve(base, relative);
+    if (target === base)
+        throw new Error('refusing to delete the worktree root');
+    if (!target.startsWith(base + sep)) {
+        throw new Error(`refusing to delete outside the worktree: ${JSON.stringify(relative)}`);
+    }
+    return target;
+}
+/**
+ * Remove one entry from the worktree, having proven it is inside it.
+ *
+ * `recursive` is not a widening of the blast radius: `resolveInside` has
+ * already pinned the target to one path git named, and git names a DIRECTORY
+ * whenever it will not look inside one — an untracked nested repository is
+ * reported as `sub/`, with no per-file lines even under
+ * `--untracked-files=all`. Without `recursive` that row is the only one in the
+ * drawer whose roll-back fails, and it fails as `EISDIR`, which says nothing
+ * to the person who clicked it.
+ *
+ * `force` makes an absent entry a success: the reader asked for it to be gone,
+ * and it is.
+ *
+ * A symlinked directory inside the worktree could still point outward; that is
+ * a repository someone already has write access to, and resolving link targets
+ * per segment on every delete would cost a stat per segment for a case git
+ * itself does not defend against.
+ *
+ * @param root - the worktree directory, absolute.
+ * @param relative - repo-relative path from a plan step.
+ */
+export async function removePathInside(root, relative) {
+    await rm(resolveInside(root, relative), { recursive: true, force: true });
+}

package/lib/git-ops.js

@@ -399,6 +399,31 @@ export function countBufferLines(bytes) {
 export function isBinaryPrefix(bytes, windowBytes) {
     return bytes.subarray(0, windowBytes).includes(0);
 }
+/**
+ * Whether a buffer is valid UTF-8, and so survives a decode/encode round trip.
+ *
+ * The editable pane hands the browser a decoded string and writes back what
+ * comes home encoded as UTF-8. For a file in any other encoding — GBK, Shift
+ * JIS, Latin-1 — that trip is LOSSY: every byte the decoder cannot read
+ * becomes U+FFFD, and writing the result replaces every non-ASCII byte in the
+ * file, including the lines nobody edited. Such a file carries no NUL byte,
+ * so the binary sniff above waves it through; only decoding it says so.
+ *
+ * `fatal` makes the decoder throw on the first invalid sequence rather than
+ * substituting, which is the whole question asked in one call and without
+ * allocating the string twice to compare it.
+ *
+ * @param bytes - the file's contents.
+ */
+export function decodesAsUtf8(bytes) {
+    try {
+        new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Clip a diff to a character cap, and SAY so when the clip happened — a
  * silently shortened diff reads as a complete one (TESTS.md H1).

package/lib/image-sniff.js

@@ -0,0 +1,197 @@
+/**
+ * Is this file actually an image, and which kind?
+ *
+ * The extension is a hint, never the answer: `.png` is a filename, not a
+ * format, and a repository full of generated assets has mislabelled files in
+ * it. So the bytes decide — every format below is identified by the signature
+ * its own specification mandates in the first few bytes.
+ *
+ * The obvious alternative is the `file-type` package, which is the mature
+ * packaging of exactly this idea. It is not used here for three reasons: it
+ * is four transitive dependencies in a package that is published to npm, it
+ * identifies two hundred types where this needs eight, and — the deciding one
+ * — it could not make the render any safer than it already is. Sniffing is
+ * the FIRST of two gates; the second is the browser's own image decoder, and
+ * that one is authoritative in a way no table can be. If the trade ever turns,
+ * `sniffImage` is the only function to replace.
+ *
+ * Membership in the table is decided by one rule: browsers render it in an
+ * `<img>` element. That is why TIFF and HEIC are absent — recognising them
+ * would only let the view promise a picture it cannot draw, and "binary file"
+ * is the more honest answer for a format the reader's browser will refuse.
+ *
+ * SVG is the one member with no magic number, because it is XML rather than a
+ * container. It is admitted anyway: rendering happens through `<img>`, which
+ * the HTML specification defines as a non-scripted context — script elements,
+ * event handlers and external references inside the document do not run and do
+ * not load. That property, not a sanitiser, is what makes it safe.
+ *
+ * Pure: no node, no fs, no git. `tests/image-sniff.test.ts` loads it directly.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/image-sniff
+ */
+/**
+ * Largest image handed to the browser, in bytes.
+ *
+ * This is a WIRE budget, not a rendering one. The bytes cross the RPC channel
+ * base64-encoded, which costs a third again on top, so a cap of four megabytes
+ * is a payload of five and a third — already the largest single message the
+ * drawer sends. Screenshots and icons, which is what repositories actually
+ * hold, sit two orders of magnitude below it.
+ */
+export const IMAGE_BYTE_CAP = 4_000_000;
+/** How many leading bytes any signature below needs. */
+const SNIFF_BYTES = 64;
+/** How much of a text file is read looking for an SVG root element.
+ *
+ *  Larger than any magic number needs because the prologue in front of that
+ *  root is unbounded in principle: an XML declaration, a DOCTYPE with an
+ *  internal subset of declarations, and any number of comments all come
+ *  first, and real files use all three. */
+const SVG_PROLOGUE_BYTES = 4096;
+/** Do `bytes` begin with these byte values at `at`? */
+function at(bytes, offset, signature) {
+    if (bytes.length < offset + signature.length)
+        return false;
+    for (let i = 0; i < signature.length; i += 1) {
+        if (bytes[offset + i] !== signature[i])
+            return false;
+    }
+    return true;
+}
+/** The bytes of an ASCII marker, so the tables read as the specs write them. */
+function ascii(text) {
+    return [...text].map(ch => ch.charCodeAt(0));
+}
+/** Little-endian uint32 at `offset`, or -1 when the buffer is too short. */
+function u32le(bytes, offset) {
+    if (bytes.length < offset + 4)
+        return -1;
+    return (bytes[offset] | (bytes[offset + 1] << 8) | (bytes[offset + 2] << 16) | (bytes[offset + 3] << 24)) >>> 0;
+}
+/** DIB header sizes BMP has ever defined. A `BM` prefix alone is two bytes of
+ *  evidence, which any text beginning "BM" would satisfy; the header size is
+ *  what makes the match a bitmap. */
+const BMP_HEADERS = [12, 16, 40, 52, 56, 64, 108, 124];
+/** ISO base-media brands that carry a still image a browser will draw. */
+const AVIF_BRANDS = ['avif', 'avis'];
+/**
+ * Identify one file from its leading bytes.
+ *
+ * @param bytes - the file's content, or at least its first {@link SNIFF_BYTES}.
+ * @returns what it is, or null for anything not in the table.
+ */
+export function sniffImage(bytes) {
+    if (bytes.length === 0)
+        return null;
+    // PNG: the eight-byte signature from the specification, chosen there
+    // precisely so that no other format collides with it.
+    if (at(bytes, 0, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) {
+        return { mime: 'image/png', kind: 'PNG' };
+    }
+    // JPEG: SOI marker, then the first marker of the next segment.
+    if (at(bytes, 0, [0xff, 0xd8, 0xff])) {
+        return { mime: 'image/jpeg', kind: 'JPEG' };
+    }
+    if (at(bytes, 0, ascii('GIF87a')) || at(bytes, 0, ascii('GIF89a'))) {
+        return { mime: 'image/gif', kind: 'GIF' };
+    }
+    // WebP is a RIFF container; the four bytes after the length field are what
+    // separate it from a WAV or an AVI.
+    if (at(bytes, 0, ascii('RIFF')) && at(bytes, 8, ascii('WEBP'))) {
+        return { mime: 'image/webp', kind: 'WebP' };
+    }
+    // ISO base media: `ftyp` box, then the brand. Also matches HEIC and MP4,
+    // which is why only the still-image AVIF brands are admitted.
+    if (at(bytes, 4, ascii('ftyp')) && AVIF_BRANDS.some(brand => at(bytes, 8, ascii(brand)))) {
+        return { mime: 'image/avif', kind: 'AVIF' };
+    }
+    if (at(bytes, 0, ascii('BM')) && BMP_HEADERS.includes(u32le(bytes, 14))) {
+        return { mime: 'image/bmp', kind: 'BMP' };
+    }
+    // ICO: reserved zero, type 1 (icon) or 2 (cursor), then a non-zero count of
+    // images. The count is the check that a run of zero bytes cannot pass.
+    if (at(bytes, 0, [0x00, 0x00, 0x01, 0x00]) && (bytes[4] | (bytes[5] << 8)) > 0) {
+        return { mime: 'image/x-icon', kind: 'ICO' };
+    }
+    if (looksLikeSvg(bytes)) {
+        return { mime: 'image/svg+xml', kind: 'SVG' };
+    }
+    return null;
+}
+/**
+ * Does this text begin an SVG document?
+ *
+ * Structural rather than a substring search: the prologue XML allows before a
+ * root element is skipped, and then the root element itself must be `svg`. A
+ * file that merely CONTAINS `<svg` somewhere — an HTML page with an inline
+ * icon, a TypeScript file with a template literal — is not one.
+ */
+function looksLikeSvg(bytes) {
+    const head = bytes.subarray(0, SVG_PROLOGUE_BYTES);
+    // A NUL rules out text before any parsing: the same test the diff side uses
+    // to call a file binary.
+    if (head.includes(0))
+        return false;
+    let text;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true }).decode(head);
+    }
+    catch {
+        // A truncated multi-byte character at the cut is not a decode failure of
+        // the FILE, so retry lenient; a genuinely non-UTF-8 file yields U+FFFD,
+        // which no prologue below accepts.
+        text = new TextDecoder('utf-8').decode(head);
+    }
+    // Strip a byte-order mark, which is legal before an XML declaration.
+    let rest = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    for (;;) {
+        rest = rest.replace(/^\s+/, '');
+        if (rest.startsWith('<?')) {
+            const end = rest.indexOf('?>');
+            // Prologue cut off by the sniff window: undecidable, so not an image.
+            if (end === -1)
+                return false;
+            rest = rest.slice(end + 2);
+            continue;
+        }
+        if (rest.startsWith('<!--')) {
+            const end = rest.indexOf('-->');
+            if (end === -1)
+                return false;
+            rest = rest.slice(end + 3);
+            continue;
+        }
+        if (rest.startsWith('<!')) {
+            // A DOCTYPE may carry an internal subset in brackets, and the
+            // declarations inside it end with '>' characters of their own —
+            // scanning to the first one lands in the middle of the subset and the
+            // root element is never reached. Real files do this: matplotlib ships
+            // an SVG whose DOCTYPE declares an ATTLIST, and it was the one file in
+            // a hundred and twenty-five thousand that this missed.
+            const bracket = rest.indexOf('[');
+            const end = rest.indexOf('>');
+            if (end === -1)
+                return false;
+            if (bracket === -1 || bracket > end) {
+                rest = rest.slice(end + 1);
+                continue;
+            }
+            const closed = rest.indexOf(']', bracket);
+            if (closed === -1)
+                return false;
+            const after = rest.indexOf('>', closed);
+            if (after === -1)
+                return false;
+            rest = rest.slice(after + 1);
+            continue;
+        }
+        break;
+    }
+    // The root element, and only `svg`: the character after the name must end
+    // it, so `<svgfoo>` is not a match.
+    if (!rest.startsWith('<svg'))
+        return false;
+    const after = rest.charAt(4);
+    return after === '' || after === '>' || after === '/' || /\s/.test(after);
+}