@kirigami/php-prepros 1.1.0 → 1.6.0

package/index.d.ts

@@ -9,7 +9,7 @@
  *
  * @example
  * ```js
- * import { render, sitemap } from '@kirigami/php-prepros';
+ * import { render, sitemap, runenv, mountPath } from '@kirigami/php-prepros';
  *
  * // Compile a single page
  * const result = await render('src/index.php');
@@ -19,6 +19,18 @@
  *
  * // Generate sitemap.xml
  * const sitemap = await sitemap();
+ *
+ * // Run an arbitrary PHP script in the same sandboxed environment
+ * const result = await runenv('scripts/purge-cache.php');
+ *
+ * // Mount a local file/directory into the sandbox before rendering
+ * await mountPath('assets/data/team.yaml');
+ *
+ * // Resize images / extract palettes through the IMG class (GD + Imagick)
+ * const { files, colors } = await processImages([
+ *   { op: 'resize', src: 'hero.jpg', width: 1200, dests: ['/project/src/images/hero-1200w.webp'] },
+ *   { op: 'palette', src: 'hero.jpg', count: 5 },
+ * ]);
  * ```
  */
 
@@ -106,4 +118,135 @@ export function render(file?: string): Promise<PreprosResult>;
  * @returns A {@link PreprosResult} with `files` containing the path to the
  *          generated `sitemap.xml`.
  */
-export function sitemap(dir?: string): Promise<PreprosResult>;
+export function sitemap(dir?: string): Promise<PreprosResult>;
+
+
+/**
+ * Run an arbitrary PHP script — not a page template — inside the same
+ * sandboxed WASM environment used by {@link render}, with the full
+ * `php-prepros` class library autoloaded and `kirigami.yaml`'s `kirigami`
+ * block available as `PREPROS::$config->data`.
+ *
+ * Useful for one-off maintenance scripts, data migrations, or CLI-style
+ * tooling that needs `CACHE`, `SCRAPER`, `IMG`, etc. without going through
+ * the page-rendering pipeline.
+ *
+ * ```js
+ * // Run a standalone PHP script
+ * const result = await runenv('scripts/purge-cache.php');
+ *
+ * // Also mount extra local paths/files into the sandbox before running
+ * const result = await runenv('scripts/build-og-images.php', ['assets/photos']);
+ *
+ * // Extra arguments are appended and available as $argv[2], $argv[3], … in the script
+ * const result = await runenv('scripts/import.php', [], '--force');
+ * ```
+ *
+ * @param script Path to a PHP file inside the project, executed with
+ *               `require_once`.
+ * @param paths  Extra local paths (files or directories) to mount into the
+ *               sandbox before the script runs.
+ * @param args   Extra string arguments appended to the script's `$argv`.
+ *
+ * @returns A {@link PreprosResult} describing what was written. Call
+ *          `PREPROS::exportFile()` inside the script for any file you want
+ *          listed in `result.files`.
+ *
+ * @throws When no `script` path is given.
+ * @throws When `script` resolves outside the project root, or doesn't exist.
+ */
+export function runenv(script: string, paths?: string[], ...args: string[]): Promise<PreprosResult>;
+
+
+/**
+ * The JavaScript-side counterpart to `PREPROS::mount()`. Mounts a local
+ * file or directory — recursively, preserving structure — into the WASM
+ * sandbox's virtual filesystem, ahead of (or between) calls to
+ * {@link render}, {@link sitemap}, or {@link runenv}.
+ *
+ * Mounting a directory only copies files whose extension is one of the
+ * defaults (`.php`, `.json`, `.yaml`, `.yml`, `.md`, `.db`, `.txt`) or
+ * listed in `prepros.mountext`, same as automatic root mounting. Mounting a
+ * single file directly copies it regardless of extension.
+ *
+ * ```js
+ * // Mount a single file at its natural virtual path (/project/<relative path>)
+ * await mountPath('assets/data/team.yaml');
+ *
+ * // Mount a whole directory, at a custom virtual path
+ * await mountPath('vendor/fonts', '/project/fonts');
+ * ```
+ *
+ * @param localPath  Path to a local file or directory. Relative paths are
+ *                    resolved against the project root.
+ * @param virtualDir  Destination path inside the WASM filesystem. Defaults
+ *                     to `/project/<localPath relative to the project root>`
+ *                     when omitted.
+ * @param php  WASM PHP instance to mount into. Defaults to the shared
+ *             singleton instance (creating it if needed).
+ */
+export function mountPath(localPath: string, virtualDir?: string, php?: unknown): Promise<void>;
+
+
+/**
+ * A single unit of work for {@link processImages}.
+ *
+ * - **`resize`** — decode `src` (resolved against `image.source`), optionally
+ *   resize it, and encode a copy to every path in `dests` (each an absolute
+ *   virtual path, e.g. `/project/src/images/hero-800w.webp`, already carrying
+ *   the target extension). Omitting both `width` and `height` re-encodes at the
+ *   source size. Staleness must be decided by the caller — every job passed in
+ *   is executed.
+ * - **`palette`** — extract `count` representative colours from `src` via
+ *   `IMG::palette()` (cached in `.cache.db`); returned in `colors`, not written.
+ */
+export type ImageJob =
+  | {
+      op: "resize";
+      /** Source path, relative to `image.source` in `kirigami.yaml`. */
+      src: string;
+      /** Target width in px. `0`/omitted = derive from height (or keep). */
+      width?: number;
+      /** Target height in px. `0`/omitted = derive from width (or keep). */
+      height?: number;
+      /** Crop to fill instead of fitting inside `width`×`height`. */
+      cover?: boolean;
+      /** Encoder quality (0-100) for lossy formats. Defaults to 82. */
+      quality?: number;
+      /** Absolute virtual destination paths to write the encoded image to. */
+      dests: string[];
+    }
+  | {
+      op: "palette";
+      /** Source path, relative to `image.source` in `kirigami.yaml`. */
+      src: string;
+      /** Number of colours to extract. Defaults to 5. */
+      count?: number;
+    };
+
+
+/**
+ * Result of {@link processImages}: a {@link PreprosResult} whose `files` lists
+ * every image written back to the host, plus the palettes that were requested.
+ */
+export interface ImageBatchResult extends PreprosResult {
+  /** Extracted palettes, keyed `"<src>:<count>"`, each a list of `#rrggbb`. */
+  colors: Record<string, string[]>;
+}
+
+
+/**
+ * Run a batch of image jobs through the same `IMG` class (GD, with the Imagick
+ * fallback) used by `IMG::asset()` and the `<img asset>` tag.
+ *
+ * This is the engine behind `@kirigami/kirigami`'s Sass `img-asset()` and
+ * `colors()` functions: one implementation, one `image:` config, one set of
+ * output filenames across Sass, PHP and HTML — no native image dependency.
+ *
+ * @param jobs List of {@link ImageJob}s. An empty list is a no-op (the WASM
+ *             runtime is not started).
+ *
+ * @returns An {@link ImageBatchResult}. Resized files are also copied to the
+ *          host at the project-relative equivalent of each `dests` entry.
+ */
+export function processImages(jobs?: ImageJob[]): Promise<ImageBatchResult>;

package/index.js

@@ -1 +1 @@
-export { render, sitemap, runenv } from "./src/prepros.js";
+export { render, sitemap, runenv, mountPath, processImages } from "./src/prepros.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirigami/php-prepros",
-  "version": "1.1.0",
+  "version": "1.6.0",
   "description": "PHP preprocessor for the Kirigami static site generator. Compile PHP page templates to clean, deployable HTML — with zero server dependency.",
   "keywords": [
     "kirigami",
@@ -28,7 +28,7 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=20.10.0",
+    "node": ">=24.0.0",
     "npm": ">=10.2.3"
   },
   "exports": {
@@ -44,8 +44,8 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@kirigami/php-wasm": "8.5.10-3",
-    "@kirigami/struct-walker": "1.0.3",
+    "@kirigami/php-wasm": "8.5.10-5",
+    "@kirigami/struct-walker": "1.0.4",
     "picomatch": "^4.0.7"
   },
   "repository": {

package/src/imagebatch.php

@@ -0,0 +1,67 @@
+<?php
+
+/**
+ * Batch image worker for the Kirigami build pipeline.
+ *
+ * Driven by @kirigami/kirigami's `sass` task (see processImages() in
+ * prepros.js): it receives a JSON list of jobs on $argv[2] and runs them
+ * through the IMG class (GD, with the Imagick fallback) so that the Sass
+ * `img-asset()` / `colors()` functions and the PHP `IMG::asset()` /
+ * `<img asset>` tag all share one engine.
+ *
+ * Job shapes:
+ *   { "op": "resize", "src": "hero.jpg", "width": 800, "height": 0,
+ *     "cover": false, "quality": 82,
+ *     "dests": ["/project/dist/images/hero-800w.webp",
+ *               "/project/src/images/hero-800w.webp"] }
+ *   { "op": "palette", "src": "hero.jpg", "count": 5 }
+ *
+ * `src` is resolved against `image.source`; `dests` are absolute virtual
+ * paths already carrying the target extension. Staleness is decided on the
+ * JS side, so every job listed here is meant to run. Generated files are
+ * returned through PREPROS::exportFile() (STD::succeed copies them back to
+ * the host); extracted palettes ride back in the `colors` map.
+ */
+
+include(__DIR__ . '/utils.inc.php');
+
+try {
+
+	$jobs = json_decode($argv[2] ?? '[]');
+	if (!is_array($jobs)) throw new Exception("Invalid jobs payload.");
+
+	$colors = [];
+
+	foreach ($jobs as $job) {
+
+		if (($job->op ?? '') === 'palette') {
+			$count = (int) ($job->count ?? 5);
+			$colors[$job->src . ':' . $count] = IMG::palette($job->src, $count);
+			continue;
+		}
+
+		// op: resize
+		$srcfile = FS::pathJoin(PREPROS::$config->image->source, $job->src);
+		if (!$mounted = PREPROS::mount($srcfile)) throw new Exception("Can't mount image: {$job->src}");
+		$localfile = current($mounted);
+		if (!is_file($localfile)) throw new Exception("Can't mount image: {$job->src}");
+
+		$width  = (int) ($job->width  ?? 0);
+		$height = (int) ($job->height ?? 0);
+		$cover  = (bool) ($job->cover ?? false);
+		$quality = isset($job->quality) ? (int) $job->quality : null;
+
+		$img = new IMG($localfile);
+		if ($width && $height) $img->resize($width, $height, $cover);
+		elseif ($width)        $img->resize($width);
+		elseif ($height)       $img->resize((int) round($img->width * $height / $img->height), $height);
+		// neither: no resize, just re-encode to the target format
+
+		foreach ($job->dests as $dest) $img->save($dest, $quality);
+	}
+
+	STD::succeed(['files' => PREPROS::getExportedFiles(), 'colors' => $colors]);
+
+} catch (Throwable $e) {
+	STD::error($e->getMessage());
+}