@kirigami/php-prepros 1.2.0 → 1.6.1

package/src/libraries/md.class.php

@@ -568,6 +568,10 @@ class MD {
         // Processed before XSS encoding — re-injected as the very last step.
         // ====================================================================
         $pluginBlocks = [];
+        // Literal, XSS-escaped source of each captured tag, keyed by the same
+        // placeholder. Used to restore a `{% tag %}` that turns out to sit
+        // inside a code span / code block as verbatim text instead of expanding it.
+        $pluginLiterals = [];
 
         /**
          * Parses an argument string into an array.
@@ -596,7 +600,7 @@ class MD {
             // Group 2: inline args (everything on the first line after the name)
             // Group 3: multi-line body (present only for block tags)
             '/\{%\s*([a-zA-Z0-9_-]+)([^\n%]*?)(?:\n([\s\S]*?))?\s*%\}/m',
-            function ($matches) use (&$pluginBlocks, $parseArgs): string {
+            function ($matches) use (&$pluginBlocks, &$pluginLiterals, $parseArgs): string {
                 $name    = strtolower(trim($matches[1]));
                 $args    = $parseArgs(trim($matches[2] ?? ''));
                 // $matches[3] exists only if the tag is multi-line
@@ -609,7 +613,8 @@ class MD {
 
                 $output      = (self::$plugins[$name])($args, $body);
                 $placeholder = "\x02PLG" . count($pluginBlocks) . "\x03";
-                $pluginBlocks[$placeholder] = $output;
+                $pluginBlocks[$placeholder]   = $output;
+                $pluginLiterals[$placeholder] = htmlspecialchars($matches[0], ENT_QUOTES, 'UTF-8');
                 return $placeholder;
             },
             $html
@@ -726,6 +731,16 @@ class MD {
             return $placeholder;
         }, $html);
 
+        // A `{% tag %}` sitting inside a code span or code block was captured
+        // by STEP 2 and is now a plugin placeholder embedded in the stored
+        // code. Swap those back for the literal (escaped) tag source so code
+        // shows `{% tag %}` verbatim instead of its rendered output — or a
+        // stray control-char placeholder that never gets restored.
+        if ($pluginLiterals) {
+            foreach ($codeBlocks as $k => $v)  $codeBlocks[$k]  = strtr($v, $pluginLiterals);
+            foreach ($inlineCodes as $k => $v) $inlineCodes[$k] = strtr($v, $pluginLiterals);
+        }
+
 
         // ====================================================================
         // STEP 3b: CHARACTER ESCAPING (\* \_ \# etc.)
@@ -1222,4 +1237,12 @@ class MD {
 
         return $html;
     }
-}
+}
+
+
+// Default Markdown plugins ({% codepen %}, {% youtube %}, {% checklist %},
+// {% callout %}) — "registered out of the box" per the README. Loaded here so
+// every entrypoint (prepros.php, runenv.php, imagebatch.php) gets them without
+// an explicit include. A project can still MD::unregisterPlugin() any of them,
+// or MD::registerPlugin() its own with the same name to override.
+include_once(__DIR__ . '/md.plugins.php');

package/src/libraries/md.plugins.php

@@ -3,7 +3,13 @@
 
 
 // =============================================================================
-// DEFAULT PLUGINS (optional, uncomment what you need)
+// DEFAULT MARKDOWN PLUGINS
+//
+// Auto-loaded from md.class.php, so these are available in every render without
+// any setup ("registered out of the box"). To drop one, call
+// MD::unregisterPlugin('name') (or md_unregister_plugin('name')) from an
+// `includes` file; to change one, MD::registerPlugin() your own under the same
+// name.
 // =============================================================================
 
 // --- CodePen (inline) ---

package/src/libraries/prepros.class.php

@@ -20,6 +20,11 @@ final class PREPROS
             if (!is_file(realpath(self::$root . $path))) continue;
             else include_once(realpath(self::$root . $path));
         }
+        // Plugin-contributed PHP (kiri 'prepros:php' hook): absolute virtual
+        // paths, mounted outside the project by @kirigami/php-prepros.
+        if (!empty($config->phpIncludes)) foreach ($config->phpIncludes as $path) {
+            if (is_file($path)) include_once($path);
+        }
     }
 
 
@@ -30,8 +35,12 @@ final class PREPROS
         if(!$file = realpath($file)) return false;
         self::$file = $file;
         
-        // to review = add the baseurl path
-        $absurl = str_replace('//', '/', str_replace('\\', '/', pathinfo(str_replace(realpath(self::$root), '', $file), PATHINFO_DIRNAME)) . '/');
+        // absolute URL path of the page's dir, prefixed with the baseurl's
+        // subpath (if any) so it stays valid when the site is deployed under a
+        // subfolder, e.g. https://kirigami.github.io/template/
+        $basepath = rtrim((string)parse_url(self::$config->data->baseurl, PHP_URL_PATH), '/');
+        $reldir = str_replace('\\', '/', pathinfo(str_replace(realpath(self::$root), '', $file), PATHINFO_DIRNAME));
+        $absurl = preg_replace('#/+#', '/', $basepath . '/' . trim($reldir, '/') . '/');
         
         $relroot = FS::getRelativePath($dir, self::$root);
         $page = self::processHook('page_info', [$file, FS::phpFileInfo($file)]);
@@ -42,8 +51,9 @@ final class PREPROS
         self::processHook('pre_render', file_get_contents($file));
 
         ob_start();
+        self::processHook('pre_before', self::$config->before);
         if (self::$config->before) include(realpath(self::$root . self::$config->before));
-        $header = ob_get_clean();
+        $header = self::processHook('post_before', ob_get_clean());
 
         if(empty($content)) {
             ob_start();
@@ -58,15 +68,22 @@ final class PREPROS
         }
 
         ob_start();
+        self::processHook('pre_after', self::$config->after);
         if (self::$config->after) include(realpath(self::$root . self::$config->after));
-        $footer = ob_get_clean();
+        $footer = self::processHook('post_after', ob_get_clean());
 
         $contents = $header . $body . $footer;
         $contents = self::processTags($contents);
         $contents = self::processHook('post_render', $contents);
 
+        if ((self::$config->head ?? true) !== false) {
+            $contents = self::injectHead($contents, $relroot);
+        }
+
         if(!empty(self::$config->format)) $contents = HTML::format($contents);
 
+        $contents = self::replaceTokens($contents);
+
         file_put_contents($target, $contents);
         self::exportFile($target);
         self::$file = '';
@@ -116,6 +133,93 @@ final class PREPROS
     }
 
 
+    /**
+     * Auto-wires each page: a theme/FOUC guard as the first child of <head>, a
+     * <link> for every `sass` task output, a <script> (no `defer`, before
+     * </body>) for every `esbuild` task output, and — when `format` is on — a
+     * tiny de-indent script that flattens the leading whitespace HTML::format()
+     * adds inside `<pre><code>`. Paths use $relroot so they work at any depth.
+     *
+     * Runs unless `prepros.head` is `false`. A single task opts out with
+     * `head: false`. A file already referenced in the page is left alone.
+     * `###TIMESTAMP###` is expanded by replaceTokens() right after.
+     */
+    private static function injectHead(string $contents, string $relroot): string
+    {
+        $inject = [];
+
+        // Theme guard — skip if the page already carries one.
+        if (!str_contains($contents, 'kirigami-theme')) {
+            $inject[] = '<script>(function(){var e=document.documentElement;'
+                . 'e.classList.add("js");try{var t=localStorage.getItem("kirigami-theme");'
+                . 'if(t==="dark"||t==="light")e.setAttribute("data-theme",t)}catch(x){}})();</script>';
+        }
+
+        $links   = [];
+        $scripts = [];
+
+        // Undo the <pre><code> indentation HTML::format() added, at parse time
+        // (before first paint), for blocks a build-time highlighter didn't
+        // already flatten (those carry child <span>s).
+        if (!empty(self::$config->format)) {
+            $scripts[] = '<script>document.querySelectorAll("pre>code").forEach(function(c){'
+                . 'if(c.children.length)return;'
+                . 'var L=c.textContent.replace(/^\n+/,"").replace(/\s+$/,"").split("\n"),n=1/0;'
+                . 'L.forEach(function(l){if(l.trim())n=Math.min(n,l.match(/^\s*/)[0].length)});'
+                . 'if(n&&n<1/0)c.textContent=L.map(function(l){return l.slice(n)}).join("\n")});</script>';
+        }
+        foreach ((array) (self::$config->tasks ?? []) as $task) {
+            $task = (array) $task;
+            if (($task['head'] ?? true) === false) continue;
+            $entry = (string) ($task['entry'] ?? '');
+            if ($entry === '') continue;
+
+            if (($task['type'] ?? '') === 'sass') {
+                $out = preg_replace('/\.s?css$/', '.min.css', $entry);
+                if ($out !== $entry && !str_contains($contents, $out)) {
+                    $links[] = '<link rel="stylesheet" href="' . $relroot . $out . '?###TIMESTAMP###">';
+                }
+            } elseif (($task['type'] ?? '') === 'esbuild') {
+                $out = preg_replace('/\.[jt]s$/', '.min.js', $entry);
+                if ($out !== $entry && !str_contains($contents, $out)) {
+                    $scripts[] = '<script src="' . $relroot . $out . '?###TIMESTAMP###"></script>';
+                }
+            }
+        }
+
+        $head = implode("\n    ", array_merge($inject, $links));
+        if ($head !== '') {
+            // Slot it right after <meta charset> when there is one (keep the
+            // charset first), otherwise right after <head>.
+            if (preg_match('/<meta\s+charset=[^>]*>/i', $contents)) {
+                $contents = preg_replace('/(<meta\s+charset=[^>]*>)/i', "$1\n    " . $head, $contents, 1);
+            } elseif (preg_match('/<head\b[^>]*>/i', $contents)) {
+                $contents = preg_replace('/(<head\b[^>]*>)/i', "$1\n    " . $head, $contents, 1);
+            }
+        }
+        if ($scripts && preg_match('/<\/body>/i', $contents)) {
+            $contents = preg_replace('/(<\/body>)/i', "    " . implode("\n    ", $scripts) . "\n$1", $contents, 1);
+        }
+
+        return $contents;
+    }
+
+
+    /**
+     * Expands the build-time text tokens in a generated file. Runs at render
+     * time (so `kiri build` / `kiri watch` previews show real values, not the
+     * literal `###YEAR###`), and again — harmlessly — on export.
+     */
+    private static function replaceTokens(string $contents): string
+    {
+        return strtr($contents, [
+            '###YEAR###'      => date('Y'),
+            '###TIMESTAMP###' => (string) time(),
+            '###TODAY###'     => date('Y-m-d'),
+        ]);
+    }
+
+
     public static function exportFile(string|array $file): void
     {
         if(is_string($file)) $file = [$file];
@@ -128,7 +232,11 @@ final class PREPROS
 
     public static function getExportedFiles(): array
     {
-        $files = array_unique(self::$files);
+        // array_unique() keeps the original keys, so any duplicate leaves a gap
+        // in the sequence — json_encode() would then emit a JSON object instead
+        // of an array and the JS side chokes ("retobj.files.map is not a
+        // function"). array_values() reindexes so it always serialises as a list.
+        $files = array_values(array_unique(self::$files));
         // sort($files);
         return $files;
     }
@@ -174,6 +282,12 @@ final class PREPROS
     }
 
 
+    public static function runHook(string $hook, $data = null)
+    {
+        return self::processHook($hook, $data);
+    }
+
+
     private static function processHook(string $hook, $data = null)
     {
         if (!empty(self::$hooks[$hook])) {

package/src/libraries/prepros.plugins.php

@@ -32,21 +32,47 @@ PREPROS::registerTag('img', function ($tag, $attrs, $body) {
 
 
 PREPROS::registerHook('page_info', function($info) {
-	list($file, $page) = $info;
+	// The hook fires with [$file, $pageInfo]; every callback then returns just
+	// the (possibly modified) $pageInfo, so a callback registered after this
+	// one receives the bare object. Accept either shape.
+	if (is_array($info)) {
+		[$file, $page] = $info;
+	} else {
+		$page = $info;
+		$file = PREPROS::$file;
+	}
 	foreach($page as $k => $v) {
 		$ext = strtolower(pathinfo($v, PATHINFO_EXTENSION));
 		if(in_array($ext, ['yaml', 'yml', 'json', 'md']) ) {
-			if(preg_match('#^https?:#i', $v)) $filename = $v;
+			$isUrl = STR::is_url($v);
+			if($isUrl) $filename = $v;
 			else $filename = pathinfo(realpath($file), PATHINFO_DIRNAME) . '/' . $v;
-			if(is_file($filename) || preg_match('#^https?:#i', $v)) {
+			if($isUrl || is_file($filename)) {
+				// Remote URLs always go through CURL::getContents — never
+				// file_get_contents, which this PHP build can't use for http(s).
+				$raw = $isUrl ? CURL::getContents($filename) : file_get_contents($filename);
+				if($raw === false) continue;
 				$page->{$k} = match ($ext) {
-					'yml', 'yaml' => YAML::parseFile($filename),
-					'json'        => json_decode(file_get_contents($filename)),
-					'md'          => MD::toHtml(file_get_contents($filename)),
+					'yml', 'yaml' => YAML::parse($raw),
+					'json'        => json_decode($raw),
+					'md'          => MD::toHtml($raw),
 					default       => $filename,
 				};
 			}
 		}
 	}
 	return $page;
+});
+
+
+// LD — capture the page under render, then inject the automatic
+// schema.org JSON-LD `<script>` into its `<head>` once the HTML is assembled.
+// Registered after the data-loading hook above so `$page` arrives resolved.
+PREPROS::registerHook('page_info', function($page) {
+	LD::capture($page);
+	return $page;
+});
+
+PREPROS::registerHook('post_render', function($html) {
+	return LD::inject($html);
 });

package/src/libraries/std.class.php

@@ -24,6 +24,9 @@ class STD {
 		$return->files = PREPROS::getExportedFiles();
 		if(is_string($props)) $return->error = $props;
 		else foreach($props as $k => $v) $return->{$k} = $v;
+		// Consumers read `->error`; keep it populated whatever key the caller
+		// used (some pass `message`) so nothing ever surfaces as "undefined".
+		if(empty($return->error)) $return->error = $return->message ?? 'Unknown error.';
 		file_put_contents(self::RESULT_PATH, json_encode($return, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE), FILE_APPEND);
 		exit(1);
 	}

package/src/libraries/str.class.php

@@ -78,7 +78,7 @@ class STR
 
 	public static function is_url(string $str): bool
 	{
-		if (!$sheme = strtolower(@parse_url($str, PHP_URL_SCHEME))) return false;
+		if (!$sheme = strtolower((string) @parse_url($str, PHP_URL_SCHEME))) return false;
 		return in_array($sheme, ['http', 'https', 'itunes', 'ftp', 'ftps', 'ssh', 'ssl', 'sftp']);
 	}
 

package/src/prepros.js

@@ -37,6 +37,10 @@ const getPHPInstance = async () => {
         preprosConfig.timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
         preprosConfig.root = joinWith('/project/', config?.kirigami?.root);
         preprosConfig.data = config.kirigami || {};
+        preprosConfig.jsonld = config.jsonld ?? null;
+        // The build task list — read by PREPROS::injectHead() to auto-wire each
+        // page's <head> with a <link>/<script> per sass/esbuild task output.
+        preprosConfig.tasks = config.tasks || [];
 
         __php = await (preprosConfig.network ? getPHPRuntimeWithNetwork() : getPHPRuntime());
         __php.setSpawnHandler((command, args, options) => spawn(command, args, options));
@@ -147,6 +151,9 @@ const run = async (args = [], script = null, mountfiles = []) => {
             const buffer = php.readFileAsBuffer(resultPath);
             retobj = JSON.parse(Buffer.from(buffer).toString('utf8'));
             retobj.debug = stdout;
+            // json_encode() turns a PHP array with gaps in its integer keys
+            // into an object — normalise back to a list before we map over it.
+            if (retobj.files && !Array.isArray(retobj.files)) retobj.files = Object.values(retobj.files);
             if(retobj.files) await Promise.all(retobj.files.map(async (file, i) => {
                 const fbuffer = php.readFileAsBuffer(file);
                 const dest = file.replace(/^\/project\//i, '');
@@ -156,23 +163,60 @@ const run = async (args = [], script = null, mountfiles = []) => {
                 retobj.files[i] = dest;
             }));
         } else {
-            retobj = { success: true, files: [], debug: stdout };
+            // No result file: PHP exited before STD::succeed()/error() — a
+            // parse error, an OOM, a die(), a hard crash. Pull whatever
+            // explanation we can out of the streams instead of a silent pass.
+            const crash = extractPhpError(stderr) || extractPhpError(stdout);
+            retobj = {
+                success: false,
+                files: [],
+                error: crash || 'PHP produced no result (exited early — check the debug output).',
+                debug: stdout,
+                stderr,
+            };
         }
     } catch (e) {
-        retobj = { success: false, error: 'Response parsing error.' + e, debug: stdout, stderr };
+        retobj = { success: false, error: 'Response parsing error: ' + (e?.message || e), debug: stdout, stderr };
     } finally {
         if (await php.fileExists(resultPath)) {
             await php.unlink(resultPath);
         }
     }
+
+    // A fatal that still managed to write a (stale/partial) result file, or
+    // warnings printed to stderr. Only a genuine fatal marker overrides a
+    // result the PHP side reported as a success; plain warnings are attached
+    // as `warnings` so a stray notice doesn't sink an otherwise-clean build.
     if (stderr) {
-        retobj = { success: false, error: stderr, debug: stdout };
+        const fatal = extractPhpError(stderr);
+        if (fatal && (!retobj || retobj.success !== false)) {
+            retobj = { success: false, files: [], error: fatal, debug: stdout, stderr };
+        } else if (retobj && retobj.success && !fatal) {
+            retobj.warnings = stderr.trim();
+        } else if (retobj && retobj.success === false && !retobj.stderr) {
+            retobj.stderr = stderr.trim();
+        }
+    }
+
+    // Never hand back a failure without a usable message.
+    if (retobj && retobj.success === false && !retobj.error) {
+        retobj.error = retobj.message || retobj.stderr || 'Unknown error.';
     }
 
     return retobj;
 }
 
 
+// Pulls the first meaningful PHP error line out of a stdout/stderr blob
+// (fatals, parse errors, uncaught throwables). Returns null when the text
+// holds nothing that looks like a hard error.
+const extractPhpError = (text) => {
+    if (!text) return null;
+    const m = text.match(/^.*\b(?:PHP\s+)?(?:Fatal error|Parse error|Uncaught\s+\w+|Recoverable fatal error)\b.*$/mi);
+    return m ? m[0].trim() : null;
+}
+
+
 const runenv = async (script, paths = [], ...args) => {
     if(!script) throw "Missing PHP file.";
     const file = path.resolve(script);
@@ -183,12 +227,43 @@ const runenv = async (script, paths = [], ...args) => {
 }
 
 
-const render = async (file = '.') => {
+// Run a batch of image jobs (resize / palette) through /prepros/imagebatch.php,
+// i.e. the IMG class (GD + Imagick). Used by @kirigami/kirigami's `sass` task so
+// that img-asset() / colors() and the PHP IMG::asset() / <img asset> tag share
+// one engine. `jobs` is the list documented in imagebatch.php; the result is a
+// PreprosResult plus a `colors` map ({ "<src>:<count>": ["#rrggbb", …] }).
+const processImages = async (jobs = []) => {
+    if (!Array.isArray(jobs) || !jobs.length) return { success: true, files: [], colors: {} };
+    const result = await run(['imagebatch', JSON.stringify(jobs)], '/prepros/imagebatch.php');
+    if (!result.colors) result.colors = {};
+    if (!result.files) result.files = [];
+    return result;
+}
+
+
+const render = async (file = '.', phpIncludes = []) => {
     const target = path.resolve(config?.kirigami?.root, file);
     const fsvm = path.join('/project', config?.kirigami?.root, file).replace(/\\/g, '/');
     await mountPath(target);
     if(config?.prepros?.before) await mountPath(path.resolve(config?.kirigami?.root, config?.prepros?.before));
     if(config?.prepros?.after) await mountPath(path.resolve(config?.kirigami?.root, config?.prepros?.after));
+
+    // Extra PHP files contributed by plugins (the kiri 'prepros:php' hook):
+    // mounted outside /project and include_once'd once, before any page
+    // renders, so they can PREPROS::registerTag()/registerHook() from PHP.
+    if (Array.isArray(phpIncludes) && phpIncludes.length) {
+        const php = await getPHPInstance();
+        const mounted = [];
+        for (let i = 0; i < phpIncludes.length; i++) {
+            const abs = path.resolve(phpIncludes[i]);
+            if (!fs.existsSync(abs)) continue;
+            const virt = `/plugins/${i}_${path.basename(abs)}`;
+            await mountPath(abs, virt, php);
+            mounted.push(virt);
+        }
+        php.preprosConfig.phpIncludes = mounted;
+    }
+
     return run([fsvm]);
 }
 
@@ -199,4 +274,4 @@ const sitemap = async () => {
 }
 
 
-export { runenv, render, sitemap, mountPath };
+export { runenv, render, sitemap, mountPath, processImages };

package/src/prepros.php

@@ -24,8 +24,15 @@ try {
         throw new Exception("Invalid target.");
     }
 
-} catch(Exception $e) {
-    STD::error(['message' => $e->getMessage()]);
+} catch(Throwable $e) {
+    // Catch Error/TypeError too, not just Exception, so a fatal in a template
+    // (a bad call, a null arg, …) still comes back as a structured result with
+    // a real message and the page that blew up — never a bare "Error: undefined".
+    STD::error([
+        'error' => $e->getMessage(),
+        'page'  => PREPROS::$file ?: ($argv[1] ?? null),
+        'where' => $e->getFile() . ':' . $e->getLine(),
+    ]);
 }
 
 

package/src/runenv.php

@@ -10,8 +10,11 @@ try {
 
     require_once($argv[1]);
 
-} catch(Exception $e) {
-    STD::error($e->getMessage());
+} catch(Throwable $e) {
+    STD::error([
+        'error' => $e->getMessage(),
+        'where' => $e->getFile() . ':' . $e->getLine(),
+    ]);
 }
 
 STD::succeed(['files' => PREPROS::getExportedFiles()]);

package/src/utils.inc.php

@@ -23,6 +23,7 @@ spl_autoload_register(function ($class) {
 		'FS'              => 'fs.class.php',
         'HTML'            => 'html.class.php',
         'IMG'             => 'img.class.php',
+        'LD'              => 'ld.class.php',
         'MD'              => 'md.class.php',
         'NORM'            => 'norm.class.php',
         'OBF'             => 'obf.class.php',
@@ -40,10 +41,19 @@ spl_autoload_register(function ($class) {
 }, true, true);
 
 
+
 $argv = array_merge(['prepros.php'], json_decode(getenv('PREPROS_ARGS'), true));
 $config = json_decode(getenv('PREPROS_CONFIG'));
 date_default_timezone_set($config->timezone);
 chdir('/project');
 
+require_once(__DIR__ . '/libraries/aliases.inc.php');
+
+PREPROS::loadConfig($config);
 
-PREPROS::loadConfig($config);
+// Bootstrap is done: config loaded, `includes` pulled in, aliases available.
+// Fires once per process, before any page renders, for every entrypoint
+// (prepros.php, runenv.php, imagebatch.php). A plugin registered from an
+// `includes` file (or prepros.plugins.php) can hook here to pull in extra
+// PHP files or wire itself up.
+PREPROS::runHook('boot', $config);