@kirigami/php-prepros 1.9.3 → 3.0.0

package/index.d.ts

@@ -9,19 +9,19 @@
  *
  * @example
  * ```js
- * import { render, sitemap, runenv, mountPath } from '@kirigami/php-prepros';
+ * import { render, sitemap, runenv, mountPath, processImages } from '@kirigami/php-prepros';
  *
  * // Compile a single page
- * const result = await render('src/index.php');
+ * const page = await render('_index.php');
  *
  * // Compile every page in the source directory
- * const result = await render('src/');
+ * const tree = await render('.');
  *
  * // Generate sitemap.xml
- * const sitemap = await sitemap();
+ * const sitemapResult = await sitemap();
  *
  * // Run an arbitrary PHP script in the same sandboxed environment
- * const result = await runenv('scripts/purge-cache.php');
+ * const purgeResult = await runenv('scripts/purge-cache.php');
  *
  * // Mount a local file/directory into the sandbox before rendering
  * await mountPath('assets/data/team.yaml');
@@ -40,7 +40,7 @@
 // ---------------------------------------------------------------------------
 
 /**
- * Returned by every prepros operation.
+ * Returned by render, sitemap and runenv; image batches extend this shape.
  */
 export interface PreprosResult {
   /** `true` when the operation completed without errors. */
@@ -50,17 +50,23 @@ export interface PreprosResult {
    * Paths of every file written to disk by this operation (relative to the
    * project root).  Includes the compiled HTML page(s) and any side-effect
    * files such as `.cache.db` or resized images produced by `IMG::save()`.
+   * May be absent if result parsing fails.
    */
-  files: string[];
+  files?: string[];
 
   /** Human-readable error message.  Only present when `success` is `false`. */
   error?: string;
 
-  /**
-   * Raw PHP stdout / stderr, useful for debugging.
-   * Only present when response parsing fails.
-   */
-  response?: string;
+  /** Captured PHP stdout. */
+  debug?: string;
+  /** PHP diagnostics attached to failure results. */
+  stderr?: string;
+  /** Nonfatal PHP diagnostics on a successful operation. */
+  warnings?: string;
+  /** Render failure context, when available. */
+  page?: string | null;
+  /** PHP source location, when available. */
+  where?: string;
 }
 
 
@@ -93,21 +99,24 @@ export interface PreprosResult {
  * Any `@tag filename` annotation whose extension is `.yaml`, `.yml`,
  * `.json`, or `.md` is automatically loaded and made available as a PHP
  * variable with the same name as the tag.  Remote URLs are supported when
- * `network: true` is set in `kirigami.yaml`.
+ * `prepros.network: true` is set in `kirigami.yaml`.
  *
  * @param file Path to a `.php` source file or a directory, relative to the
- *             project root.  Defaults to `.` (the entire source tree).
+ *             configured `kirigami.root`. Defaults to `.` (the entire source tree).
  *
+ * @param phpIncludes Local plugin PHP files to mount and include before rendering.
+ *                    Missing files are skipped; defaults to an empty list.
  * @returns A {@link PreprosResult} describing what was written.
  *
  * @throws When the `kirigami.yaml` config is missing or malformed.
  * @throws When `kirigami.root` does not exist on disk.
  */
-export function render(file?: string): Promise<PreprosResult>;
+export function render(file?: string, phpIncludes?: string[]): Promise<PreprosResult>;
 
 
 /**
- * Generate a `sitemap.xml` at the source root.
+ * Generate sitemap.xml and robots.txt at the source root, plus humans.txt
+ * when configured author data provides content.
  *
  * Scans every `_index.php` found in the source tree and produces a
  * standard Sitemaps 0.9 XML document.  Priority is calculated from depth
@@ -118,7 +127,7 @@ 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(): Promise<PreprosResult>;
 
 
 /**
@@ -133,19 +142,19 @@ export function sitemap(dir?: string): Promise<PreprosResult>;
  *
  * ```js
  * // Run a standalone PHP script
- * const result = await runenv('scripts/purge-cache.php');
+ * const purgeResult = 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']);
+ * const imageResult = await runenv('scripts/build-og-images.php', ['assets/photos/hero.jpg']);
  *
  * // Extra arguments are appended and available as $argv[2], $argv[3], … in the script
- * const result = await runenv('scripts/import.php', [], '--force');
+ * const importResult = 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 paths  Extra project files to mount before execution. Missing files
+ *               are skipped. Use mountPath() separately for directories.
  * @param args   Extra string arguments appended to the script's `$argv`.
  *
  * @returns A {@link PreprosResult} describing what was written. Call
@@ -153,11 +162,29 @@ export function sitemap(dir?: string): Promise<PreprosResult>;
  *          listed in `result.files`.
  *
  * @throws When no `script` path is given.
- * @throws When `script` resolves outside the project root, or doesn't exist.
+ * @throws When the script is missing, an input is a directory, or any input
+ *         escapes the project lexically or through a symbolic link.
  */
 export function runenv(script: string, paths?: string[], ...args: string[]): Promise<PreprosResult>;
 
 
+/**
+ * Like {@link runenv}, for a script shipped inside a plugin package. A linked
+ * or workspace plugin lives outside the project, so the script is contained
+ * by `pluginRoot` instead, and mounted under `/plugin-scripts/<package dir>/`.
+ * The caller must pass the resolved package directory of an active plugin.
+ *
+ * @param script      Path of the PHP script, absolute or relative to `pluginRoot`.
+ * @param pluginRoot  The plugin's package directory.
+ * @param paths       Extra project files to mount, as for {@link runenv}.
+ * @param args        Extra string arguments appended to the script's `$argv`.
+ *
+ * @throws When the script is missing, is a directory, or escapes
+ *         `pluginRoot` lexically or through a symbolic link.
+ */
+export function runPluginScript(script: string, pluginRoot: 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
@@ -182,11 +209,18 @@ export function runenv(script: string, paths?: string[], ...args: string[]): Pro
  * @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).
+ * @param php  WASM PHP instance to mount into. Defaults to PHP-prepros's
+ *             owned instance (creating it if needed).
  */
 export function mountPath(localPath: string, virtualDir?: string, php?: unknown): Promise<void>;
 
+/**
+ * Waits for queued PHP operations, disposes the owned runtime and clears its
+ * cached configuration and mounts. The next operation creates a fresh runtime.
+ * Project.reload() also invalidates core's plugin PHP include list.
+ */
+export function resetRuntime(): Promise<void>;
+
 
 /**
  * A single unit of work for {@link processImages}.
@@ -230,6 +264,8 @@ export type ImageJob =
  * every image written back to the host, plus the palettes that were requested.
  */
 export interface ImageBatchResult extends PreprosResult {
+  /** Always normalized to an array, including on failure. */
+  files: string[];
   /** Extracted palettes, keyed `"<src>:<count>"`, each a list of `#rrggbb`. */
   colors: Record<string, string[]>;
 }
@@ -249,4 +285,4 @@ export interface ImageBatchResult extends PreprosResult {
  * @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>;
+export function processImages(jobs?: ImageJob[]): Promise<ImageBatchResult>;

package/index.js

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

package/package.json

@@ -1,59 +1,59 @@
-{
-  "name": "@kirigami/php-prepros",
-  "version": "1.9.3",
-  "description": "PHP preprocessor for the Kirigami static site generator. Compile PHP page templates to clean, deployable HTML — with zero server dependency.",
-  "keywords": [
-    "kirigami",
-    "php",
-    "preprocessor",
-    "static-site-generator",
-    "ssg",
-    "wasm",
-    "php-wasm",
-    "markdown",
-    "yaml",
-    "github-pages",
-    "pages"
-  ],
-  "license": "MIT",
-  "author": "Maxime Larrivée-Roy",
-  "type": "module",
-  "main": "index.js",
-  "types": "index.d.ts",
-  "files": [
-    "index.js",
-    "index.d.ts",
-    "src/",
-    "LICENSE",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=24.0.0",
-    "npm": ">=10.2.3"
-  },
-  "exports": {
-    ".": {
-      "import": "./index.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "dependencies": {
-    "@kirigami/php-wasm": "8.5.10-5",
-    "@kirigami/struct-walker": "1.0.5",
-    "picomatch": "^4.0.7"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/php-kirigami/kirigami.git"
-  },
-  "homepage": "https://php-kirigami.github.io",
-  "bugs": {
-    "url": "https://github.com/php-kirigami/kirigami/issues"
-  }
-}
+{
+  "name": "@kirigami/php-prepros",
+  "version": "3.0.0",
+  "description": "PHP preprocessor for the Kirigami static site generator. Compile PHP page templates to clean, deployable HTML — with zero server dependency.",
+  "keywords": [
+    "kirigami",
+    "php",
+    "preprocessor",
+    "static-site-generator",
+    "ssg",
+    "wasm",
+    "php-wasm",
+    "markdown",
+    "yaml",
+    "github-pages",
+    "pages"
+  ],
+  "license": "GPL-3.0-or-later",
+  "author": "Maxime Larrivée-Roy",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24.0.0",
+    "npm": ">=10.2.3"
+  },
+  "exports": {
+    ".": {
+      "import": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test --test-concurrency=1 \"test/*.test.js\""
+  },
+  "dependencies": {
+    "@kirigami/php-wasm": "8.5.11",
+    "@kirigami/struct-walker": "1.0.6",
+    "picomatch": "^4.0.7"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/php-kirigami/kirigami.git"
+  },
+  "homepage": "https://php-kirigami.github.io",
+  "bugs": {
+    "url": "https://github.com/php-kirigami/kirigami/issues"
+  }
+}

package/src/imagebatch.php

@@ -1,67 +1,68 @@
-<?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());
-}
+<?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.
+ */
+
+// Framework bootstrap (autoloader, $argv/$config, aliases, `boot` hook) is
+// loaded via php.ini's auto_prepend_file, not an explicit include here.
+
+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());
+}