@bleedingdev/ipx 3.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Pooya Parsa <pooya@pi0.io>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# @bleedingdev/ipx
+
+A minimal, distributable sidecar fork of [`ipx`](https://github.com/unjs/ipx) — "High
+performance, secure and easy-to-use image optimizer" — by Pooya Parsa and the UnJS
+contributors, MIT licensed. The upstream `LICENSE` is preserved verbatim next to this file.
+
+Forked from **`ipx@3.1.1`**. Published as **`@bleedingdev/ipx@3.2.0`**.
+
+The `dist/` tree here is the upstream published build, vendored byte-for-byte except for the
+hunks listed below. Upstream ships no TypeScript sources in the npm tarball, so this fork
+patches the published chunks directly rather than rebuilding from source; that keeps the diff
+against `ipx@3.1.1` small enough to re-audit by eye on every upstream bump.
+
+## Why this fork exists
+
+`@modern-js/image` depends on `sharp@^0.35.3`, but `ipx@3.1.1` declares `"sharp": "^0.34.3"`
+as a **plain dependency**. A `0.x` caret does not admit `0.35.x`
+(`semver.satisfies("0.35.3", "^0.34.3") === false`), so every consumer of the published
+`@modern-js/image` also installs a second, older `sharp` — currently `sharp@0.34.5` — behind
+IPX. Plain dependencies cannot be redirected from a consumer's manifest: `pnpm.overrides` and
+`pnpm.patchedDependencies` apply only to the root project and are not carried into a published
+package. Forking the dependency and aliasing it in `@modern-js/image` is the only distributable
+fix.
+
+The version is a **stable** `3.2.0` on purpose. Both `@rsbuild-image/core` and
+`@rsbuild-image/react` declare the peer range `"ipx": ">=3.0.3"`, and npm evaluates non-wildcard
+peer ranges with a loose-only `semver.satisfies` that **excludes prereleases**. A prerelease
+version such as `3.2.0-ultramodern.1` would pass pnpm but fail strict npm and yarn-classic
+consumers.
+
+## Fork delta vs `ipx@3.1.1`
+
+### 1. `sharp` dependency range: `^0.34.3` → `^0.35.3` (`package.json`)
+
+Aligns IPX with the `sharp` version `@modern-js/image` already declares, so a single, current
+`sharp` is installed for the whole image pipeline.
+
+### 2. `sharpen` modifier remapped to Sharp 0.35's object form (`dist/shared/*`, 2 hunks)
+
+Sharp 0.35 **removed** the deprecated positional `sharpen(sigma, flat, jagged)` signature. Its
+replacement (`sharp/dist/operation.cjs`, `function sharpen (options)`) reads a plain object and
+falls through to `this.options.sharpenSigma = -1` — the "mild sharpen" default — for **any**
+non-object argument. Upstream's call therefore does not throw under Sharp 0.35; it *silently
+discards every parameter the user asked for*.
+
+Upstream (`dist/shared/ipx.CXJeaylD.mjs:213-217` and `dist/shared/ipx.GUc23orS.cjs:220-224`):
+
+```js
+apply: (_context, pipe, sigma, flat, jagged) => {
+  return pipe.sharpen(sigma, flat, jagged);
+}
+```
+
+This fork maps the IPX modifier arguments onto `{ sigma, m1, m2 }`, coercing each to a number
+(IPX arguments arrive through `VArg`, i.e. `destr`, so a URL segment may still be a string) and
+treating `undefined`, `null`, an empty segment, and a non-numeric segment as "absent" — which
+yields Sharp's argument-less mild sharpen instead of a thrown parameter error. `NaN` is never
+handed to Sharp.
+
+Behaviour notes:
+
+- `?sharpen` (bare, no value) now applies Sharp's mild sharpen. Under `ipx@3.1.1` + `sharp@0.34`
+  this threw `Expected number between 0.01 and 10000 for sigma`; the new behaviour matches
+  Sharp's own no-argument contract and IPX's convention that a bare modifier is a flag.
+- The accepted `sigma` range narrows from Sharp 0.34's deprecated positional range
+  (`0.01`–`10000`) to Sharp 0.35's object-form range (`0.000001`–`10`). This is an upstream Sharp
+  restriction, not a fork decision; out-of-range values raise Sharp's own parameter error rather
+  than being silently clamped.
+- `flat`/`jagged` map to `m1`/`m2`, whose valid range widens to `0`–`1000000` (Sharp 0.34's
+  deprecated path capped them at `10000`).
+
+### 3. CLI banner version string `3.1.1` → `3.2.0` (`dist/cli.mjs`, `dist/cli.cjs`)
+
+Cosmetic and non-functional: the version is inlined into the published CLI at build time, so
+without this hunk `ipx --version` would disagree with this package's manifest. The bin name
+itself is unchanged (`"bin": "./bin/ipx.mjs"` in string form, which
+`npm-normalize-package-bin` resolves to the basename `ipx`), so the `ipx` CLI contract is
+preserved despite the scoped package name.
+
+## Sharp 0.34 → 0.35 audit (no other remaps required)
+
+Every Sharp method IPX's modifier table reaches was compared between `sharp@0.34.5`
+(`lib/*.js`) and `sharp@0.35.3` (`dist/*.cjs`): `resize`, `trim`, `extend`, `extract`, `rotate`,
+`flip`, `flop`, `sharpen`, `median`, `blur`, `flatten`, `gamma`, `negate`, `normalize`,
+`threshold`, `modulate`, `tint`, `grayscale`, plus the pipeline's `toFormat` and `toBuffer`.
+
+- **`sharpen` is the only removal.** Everything else is byte-identical or differs only in added
+  upper-bound validation (`extend` now rejects > 10000 px per edge; `extract` now rejects
+  > 100000000; `trim` gained an optional `margin` option). None of those changes reject an input
+  that `ipx@3.1.1` previously produced valid output for.
+- The `trim` modifier passes a bare number to `sharp.trim()`, which throws
+  `Expected object for trim`. That is a **pre-existing upstream IPX bug**, identical under Sharp
+  0.34.5 and 0.35.3, and is deliberately left unchanged here so this fork stays a
+  security/compatibility fork rather than a behaviour fork.
+
+## Verification
+
+`scripts/verify-sharpen.mjs` exercises the remap end-to-end against a real image through
+`createIPX` + `ipxFSStorage` and asserts that `sigma`, `flat` and `jagged` actually reach
+libvips (different values must produce different bytes). Run it from a checkout where the
+runtime dependencies resolve:
+
+```sh
+node packages/sidecar/ipx/scripts/verify-sharpen.mjs [imageDir]
+```
+
+Running the same script against the unpatched `ipx@3.1.1` dist on `sharp@0.35.3` fails both
+differentiation assertions — every `sharpen` variant returns the identical mild-sharpen buffer —
+which is exactly the silent regression this fork removes.
+
+## Maintenance
+
+On an upstream `ipx` release, re-vendor `bin/`, `dist/` and `LICENSE`, then re-apply the hunks in
+"Fork delta" (or drop them if upstream has adopted Sharp 0.35). `diff -ru` against the upstream
+tarball must show those hunks and nothing else.

package/bin/ipx.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli.mjs";

package/dist/cli.cjs

@@ -0,0 +1,63 @@
+'use strict';
+
+const listhen = require('listhen');
+const citty = require('citty');
+const cli = require('listhen/cli');
+const nodeFs = require('./shared/ipx.GUc23orS.cjs');
+require('defu');
+require('ufo');
+require('h3');
+require('image-meta');
+require('destr');
+require('@fastify/accept-negotiator');
+require('etag');
+require('ofetch');
+require('pathe');
+
+const name = "ipx";
+const version = "3.2.0";
+const description = "High performance, secure and easy-to-use image optimizer.";
+
+const serve = citty.defineCommand({
+  meta: {
+    description: "Start IPX Server"
+  },
+  args: {
+    dir: {
+      type: "string",
+      required: false,
+      description: "Directory to serve (default: current directory) ENV: IPX_FS_DIR"
+    },
+    domains: {
+      type: "string",
+      required: false,
+      description: "Allowed domains (comma separated) ENV: IPX_HTTP_DOMAINS"
+    },
+    ...cli.getArgs()
+  },
+  async run({ args }) {
+    const ipx = nodeFs.createIPX({
+      storage: nodeFs.ipxFSStorage({
+        dir: args.dir
+      }),
+      httpStorage: nodeFs.ipxHttpStorage({
+        domains: args.domains
+      })
+    });
+    await listhen.listen(nodeFs.createIPXNodeServer(ipx), {
+      name: "IPX",
+      ...cli.parseArgs(args)
+    });
+  }
+});
+const main = citty.defineCommand({
+  meta: {
+    name,
+    version,
+    description
+  },
+  subCommands: {
+    serve
+  }
+});
+citty.runMain(main);

package/dist/cli.d.cts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/cli.d.mts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/cli.mjs

@@ -0,0 +1,61 @@
+import { listen } from 'listhen';
+import { defineCommand, runMain } from 'citty';
+import { getArgs, parseArgs } from 'listhen/cli';
+import { c as createIPX, i as ipxHttpStorage, g as ipxFSStorage, e as createIPXNodeServer } from './shared/ipx.CXJeaylD.mjs';
+import 'defu';
+import 'ufo';
+import 'h3';
+import 'image-meta';
+import 'destr';
+import '@fastify/accept-negotiator';
+import 'etag';
+import 'ofetch';
+import 'pathe';
+
+const name = "ipx";
+const version = "3.2.0";
+const description = "High performance, secure and easy-to-use image optimizer.";
+
+const serve = defineCommand({
+  meta: {
+    description: "Start IPX Server"
+  },
+  args: {
+    dir: {
+      type: "string",
+      required: false,
+      description: "Directory to serve (default: current directory) ENV: IPX_FS_DIR"
+    },
+    domains: {
+      type: "string",
+      required: false,
+      description: "Allowed domains (comma separated) ENV: IPX_HTTP_DOMAINS"
+    },
+    ...getArgs()
+  },
+  async run({ args }) {
+    const ipx = createIPX({
+      storage: ipxFSStorage({
+        dir: args.dir
+      }),
+      httpStorage: ipxHttpStorage({
+        domains: args.domains
+      })
+    });
+    await listen(createIPXNodeServer(ipx), {
+      name: "IPX",
+      ...parseArgs(args)
+    });
+  }
+});
+const main = defineCommand({
+  meta: {
+    name,
+    version,
+    description
+  },
+  subCommands: {
+    serve
+  }
+});
+runMain(main);

package/dist/index.cjs

@@ -0,0 +1,62 @@
+'use strict';
+
+const nodeFs = require('./shared/ipx.GUc23orS.cjs');
+const h3 = require('h3');
+require('defu');
+require('ufo');
+require('image-meta');
+require('destr');
+require('@fastify/accept-negotiator');
+require('etag');
+require('ofetch');
+require('pathe');
+
+function unstorageToIPXStorage(storage, _options = {}) {
+  const options = typeof _options === "string" ? { prefix: _options } : _options;
+  const resolveKey = (id) => options.prefix ? `${options.prefix}:${id}` : id;
+  return {
+    name: "ipx:" + (storage.name || "unstorage"),
+    async getMeta(id, opts = {}) {
+      if (!storage.getMeta) {
+        return;
+      }
+      const storageKey = resolveKey(id);
+      const meta = await storage.getMeta(storageKey, opts);
+      return meta;
+    },
+    async getData(id, opts = {}) {
+      if (!storage.getItemRaw) {
+        return;
+      }
+      const storageKey = resolveKey(id);
+      let data = await storage.getItemRaw(storageKey, opts);
+      if (!data) {
+        return;
+      }
+      if (data instanceof Blob) {
+        data = await data.arrayBuffer();
+      }
+      try {
+        return Buffer.from(data);
+      } catch (error) {
+        throw h3.createError({
+          statusCode: 500,
+          statusText: `IPX_STORAGE_ERROR`,
+          message: `Failed to parse storage data to Buffer:
+${error.message}`,
+          cause: error
+        });
+      }
+    }
+  };
+}
+
+exports.createIPX = nodeFs.createIPX;
+exports.createIPXH3App = nodeFs.createIPXH3App;
+exports.createIPXH3Handler = nodeFs.createIPXH3Handler;
+exports.createIPXNodeServer = nodeFs.createIPXNodeServer;
+exports.createIPXPlainServer = nodeFs.createIPXPlainServer;
+exports.createIPXWebServer = nodeFs.createIPXWebServer;
+exports.ipxFSStorage = nodeFs.ipxFSStorage;
+exports.ipxHttpStorage = nodeFs.ipxHttpStorage;
+exports.unstorageToIPXStorage = unstorageToIPXStorage;