express-hbs 2.5.0 → 2.5.1

package/.claude/worktrees/security-patches-review-c621ea/.oxlintrc.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "categories": {
+    "correctness": "error",
+    "suspicious": "warn"
+  },
+  "env": {
+    "node": true,
+    "es2024": true
+  },
+  "rules": {
+    "no-console": "error"
+  },
+  "overrides": [
+    {
+      "files": ["test/**/*.js"],
+      "env": {
+        "mocha": true
+      },
+      "rules": {
+        "no-console": "off",
+        "no-unused-vars": "off"
+      }
+    },
+    {
+      "files": ["lib/hbs.js", "example/**/*.js"],
+      "rules": {
+        "no-console": "off"
+      }
+    }
+  ]
+}

package/.claude/worktrees/security-patches-review-c621ea/AGENTS.md

@@ -0,0 +1,40 @@
+# express-hbs agent notes
+
+`express-hbs` is a CommonJS Express view-engine library. Read `README.md` for
+the public API and usage examples before changing behavior.
+
+## Commands
+
+Use the pnpm version pinned in package.json on Node.js 22.12 or later.
+
+```sh
+pnpm install --frozen-lockfile
+pnpm lint
+pnpm test
+pnpm coverage
+```
+
+`pnpm test` runs `mocha` and then `pnpm lint` through the `posttest` script.
+`pnpm coverage` runs the same test suite under `nyc` and enforces the coverage
+thresholds in `package.json`.
+
+## Boundaries
+
+- Do not edit `pnpm-lock.yaml` by hand. Regenerate it with `pnpm install`.
+- Keep `lib/hbs.js` and `lib/resolver.js` CommonJS; this package does not use
+  ESM.
+- Treat files under `test/views/**`, `test/issues/**`, and `example/views/**`
+  as rendering fixtures. Seemingly odd whitespace, malformed markup, or partial
+  names may be intentional test coverage.
+- Keep the security warning around user-controlled `layout` values and
+  `restrictLayoutsTo` in sync with behavior.
+
+## Style notes
+
+- Formatting is enforced by `oxfmt`; run `pnpm lint:fix` rather than doing large
+  manual formatting sweeps.
+- The formatter intentionally ignores Handlebars, HTML, CSS, lockfile, and
+  fixture data files. Preserve their existing shape unless the test expectation
+  itself is being changed.
+- Add or update tests for layout resolution, partial loading, async helpers,
+  template options, and caching changes.

package/.claude/worktrees/security-patches-review-c621ea/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2012-2025 Barc, Inc., Ghost Foundation
+
+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/.claude/worktrees/security-patches-review-c621ea/README.md

@@ -0,0 +1,333 @@
+# express-hbs
+
+Express Handlebars template engine for Express apps, with nested layouts,
+named content blocks, cached partials, i18n helpers, and asynchronous helpers.
+
+`express-hbs` exposes Express-compatible view engine functions and a shared
+Handlebars instance. It is used by apps that want Handlebars templates with
+layout inheritance and block-style content regions while keeping the familiar
+`app.engine()` integration.
+
+## Requirements
+
+- Node.js 22 or later
+- the pinned pnpm version when working on this repository
+
+## v2.0.0
+
+Version 2 was a rewrite and cleanup, with no known breaking changes. Lots of bugs were fixed which may have subtly changed behaviour.
+
+Full details: https://github.com/TryGhost/express-hbs/releases/tag/2.0.0
+
+## v1.0.0 Breaking Changes
+
+If you're upgrading from v0.8.4 to v1.0.0 there are some potentially breaking changes to be aware of:
+
+1. Handlebars @v4.0.5 - please see the [handlebars v4.0 compatibility notes](https://github.com/wycats/handlebars.js/blob/master/release-notes.md#v400---september-1st-2015)
+2. The file extension for partial files must now match the extension configured in `extname` - please see [the PR](https://github.com/TryGhost/express-hbs/pull/88)
+
+## Usage
+
+Register the engine with Express using `hbs.express4()`.
+
+```js
+var hbs = require('express-hbs');
+
+// Use `.hbs` for extensions and find partials in `views/partials`.
+app.engine('hbs', hbs.express4({
+  partialsDir: __dirname + '/views/partials'
+}));
+app.set('view engine', 'hbs');
+app.set('views', __dirname + '/views');
+```
+
+`hbs.express3()` is still available for legacy apps and accepts the same
+options:
+
+```js
+app.engine('hbs', hbs.express3({
+  partialsDir: __dirname + '/views/partials'
+}));
+```
+
+Options for `express3()` and `express4()`:
+
+```js
+hbs.express4({
+  partialsDir: "{String/Array} [Required] Path to partials templates, one or several directories",
+
+  // OPTIONAL settings
+  restrictLayoutsTo: "{String} Absolute path to a directory to restrict layout directive reading from",
+  blockHelperName: "{String} Override 'block' helper name.",
+  contentHelperName: "{String} Override 'contentFor' helper name.",
+  defaultLayout: "{String} Absolute path to default layout template",
+  extname: "{String} Extension for templates & partials, defaults to `.hbs`",
+  handlebars: "{Module} Use external handlebars instead of express-hbs dependency",
+  i18n: "{Object} i18n object",
+  layoutsDir: "{String} Path to layout templates",
+  templateOptions: "{Object} options to pass to template()",
+  beautify: "{Boolean} whether to pretty print HTML, see github.com/einars/js-beautify .jsbeautifyrc",
+
+  // override the default compile
+  onCompile: function(exhbs, source, filename) {
+    var options;
+    if (filename && filename.indexOf('partials') > -1) {
+      options = {preventIndent: true};
+    }
+    return exhbs.handlebars.compile(source, options);
+  }
+});
+```
+
+## Syntax
+
+To mark where a layout should insert page content:
+
+    {{{body}}}
+
+To declare a block placeholder in a layout:
+
+    {{{block "pageScripts"}}}
+
+To define block content in a page:
+
+    {{#contentFor "pageScripts"}}
+      CONTENT HERE
+    {{/contentFor}}
+
+## Layouts
+
+There are three ways to use a layout, listed in precedence order:
+
+1.  Declarative within a page. Use handlebars comment
+
+        {{!< LAYOUT}}
+
+    Layout file resolution:
+
+        If path starts with '.'
+            LAYOUT is relative to template
+        Else If `layoutsDir` is set
+            LAYOUT is relative to `layoutsDir`
+        Else
+            LAYOUT from path.resolve(dirname(template), LAYOUT)
+
+2.  As an option to render
+
+    ⚠️ Passing user-controlled data into the `layout` option can read arbitrary
+    files unless `restrictLayoutsTo` confines layout resolution to a safe
+    directory. Do not call `res.render('index', req.query)` or similar without
+    setting `restrictLayoutsTo`.
+
+    ```js
+    res.render('veggies', {
+      title: 'My favorite veggies',
+      veggies: veggies,
+      layout: 'layout/veggie'
+    });
+    ```
+
+    This option also allows layout suppression, including the default layout and
+    template-declared layouts, by passing a falsey JavaScript value:
+
+    ```js
+    res.render('veggies', {
+      title: 'My favorite veggies',
+      veggies: veggies,
+      layout: null // render without using a layout template
+    });
+    ```
+
+    Layout file resolution:
+
+        If path starts with '.'
+            layout is relative to template
+        Else If `layoutsDir` is set
+            layout is relative to `layoutsDir`
+        Else
+            layout from path.resolve(viewsDir, layout)
+
+3.  Lastly, use `defaultLayout` if specified in hbs configuration options.
+
+Layouts can be nested: just include a declarative layout tag within any layout
+template to have its content included in the declared "parent" layout.  Be
+aware that too much nesting can impact performances, and stay away from
+infinite loops!
+
+## Helpers
+
+### Synchronous helpers
+
+```js
+hbs.registerHelper('link', function(text, options) {
+  var attrs = [];
+  for(var prop in options.hash) {
+    attrs.push(prop + '="' + options.hash[prop] + '"');
+  }
+  return new hbs.SafeString(
+    "<a " + attrs.join(" ") + ">" + text + "</a>"
+  );
+});
+```
+
+in markup
+```
+{{{link 'barc.com' href='http://barc.com'}}}
+```
+
+### Asynchronous helpers
+
+```js
+hbs.registerAsyncHelper('readFile', function(filename, cb) {
+  fs.readFile(path.join(viewsDir, filename), 'utf8', function(err, content) {
+    cb(new hbs.SafeString(content));
+  });
+});
+```
+
+in markup
+```
+{{{readFile 'tos.txt'}}}
+```
+
+
+## i18n support
+
+Express-hbs supports [i18n](https://github.com/mashpie/i18n-node)
+
+```js
+var i18n = require('i18n');
+
+// minimal config
+i18n.configure({
+    locales: ['en', 'fr'],
+    cookie: 'locale',
+    directory: __dirname + "/locales"
+});
+
+app.engine('hbs', hbs.express3({
+    // ... options from above
+    i18n: i18n,  // registers __ and __n helpers
+}));
+app.set('view engine', 'hbs');
+app.set('views', viewsDir);
+
+// cookies are needed
+app.use(express.cookieParser());
+
+// init i18n module
+app.use(i18n.init);
+```
+
+## Engine Instances
+
+Create isolated engine instances with their own cache system and handlebars engine.
+
+```js
+var hbs = require('express-hbs');
+var instance1 = hbs.create();
+var instance2 = hbs.create();
+```
+
+## Template options
+
+The main use case for template options is setting the Handlebars `data` object,
+which creates global template variables accessible with an `@` prefix.
+
+Template options can be passed when creating an engine instance, updated with
+`updateTemplateOptions(templateOptions)`, or set for one request with
+`updateLocalTemplateOptions(locals, templateOptions)` on `res.locals`.
+
+Both of these methods have a companion method `getTemplateOptions()` and `getLocalTemplateOptions(locals)`, which should be used when extending or merging the current options.
+
+## Example
+
+in File `app.js`
+
+```js
+// http://expressjs.com/api.html#app.locals
+app.locals({
+    'PROD_MODE': 'production' === app.get('env')
+});
+
+```
+
+File `views/layout/default.hbs`
+
+```html
+<html>
+  <head>
+    <title>{{title}}</title>
+    <link type="text/css" rel="stylesheet" href="/css/style.css"/>
+    {{{block "pageStyles"}}}
+  </head>
+  <body>
+    {{{body}}}
+
+    {{> scripts}}
+
+    {{#if PROD_MODE}}
+    {{{block 'googleAnalyticsScripts'}}}
+    {{/if}}
+
+  </body>
+</html>
+```
+
+
+File `views/index.hbs`
+
+```html
+{{!< default}}
+
+{{#contentFor 'pageStyles'}}
+<style>
+  .clicker {
+    color: blue;
+  };
+</style>
+{{/contentFor}}
+
+<h1>{{title}}</h1>
+<p class="clicker">Click me!</p>
+```
+
+To run example project
+
+```sh
+pnpm install
+node example/app.js
+```
+
+The example server listens on <http://localhost:3000>.
+
+## Testing
+
+Install dependencies and run the test suite:
+
+```sh
+pnpm install
+pnpm test
+```
+
+Useful maintainer commands:
+
+```sh
+pnpm lint          # oxlint plus oxfmt --check
+pnpm lint:fix      # apply safe lint fixes and formatting
+pnpm coverage      # mocha under nyc with enforced coverage thresholds
+```
+
+
+## Credits
+
+Inspiration and code from [donpark/hbs](https://github.com/donpark/hbs)
+
+Big thanks to all [CONTRIBUTORS](https://github.com/TryGhost/express-hbs/contributors)
+
+
+## License
+
+The MIT License (MIT)
+
+Copyright (c) 2012-2026 Barc, Inc., Ghost Foundation - Released under the [MIT license](LICENSE).

package/.claude/worktrees/security-patches-review-c621ea/SECURITY.md

@@ -0,0 +1,9 @@
+# Reporting Security Vulnerabilities
+
+Potential security vulnerabilities can be reported directly us at `security@ghost.org`. The Ghost Security Team communicates privately and works in a secured, isolated repository for tracking, testing, and resolving security-related issues.
+
+The full, up-to-date details of our security policy and procedure can always be found in our documentation:
+
+https://ghost.org/docs/security/
+
+Please refer to this before emailing us. Thanks for helping make Ghost safe for everyone 🙏.

package/.claude/worktrees/security-patches-review-c621ea/example/app-layoutsDir.js

@@ -0,0 +1,99 @@
+// pnpm add express express-hbs
+
+'use strict';
+
+var express = require('express');
+var app = express();
+var hbs = require('..'); // should be `require('express-hbs')` outside of this example
+var fs = require('fs');
+var fp = require('path');
+
+function relative(path) {
+  return fp.join(__dirname, path);
+}
+var viewsDir = relative('views');
+
+app.use(express.static(relative('public')));
+
+// Hook in express-hbs and tell it where known directories reside
+app.engine(
+  'hbs',
+  hbs.express4({
+    partialsDir: [relative('views/partials'), relative('views/partials-other')],
+    layoutsDir: relative('views/layout'),
+    defaultLayout: relative('views/layout/default.hbs'),
+    restrictLayoutsTo: relative('views/layout'),
+  }),
+);
+app.set('view engine', 'hbs');
+app.set('views', relative('views'));
+
+// Register sync helper
+hbs.registerHelper('link', function (text, options) {
+  var attrs = [];
+  for (var prop in options.hash) {
+    attrs.push(prop + '="' + options.hash[prop] + '"');
+  }
+  return new hbs.SafeString('<a ' + attrs.join(' ') + '>' + text + '</a>');
+});
+
+// Register Async helpers
+hbs.registerAsyncHelper('readFile', function (filename, cb) {
+  fs.readFile(fp.join(viewsDir, filename), 'utf8', function (err, content) {
+    if (err) console.error(err);
+    cb(new hbs.SafeString(content));
+  });
+});
+
+var fruits = [{ name: 'apple' }, { name: 'orange' }, { name: 'pear' }];
+
+var veggies = [{ name: 'asparagus' }, { name: 'carrot' }, { name: 'spinach' }];
+
+app.get('/', function (req, res) {
+  res.render('index', {
+    title: 'express-hbs example',
+  });
+});
+
+app.get('/fruits', function (req, res) {
+  res.render('fruits/index-layoutsDir', {
+    title: 'My favorite fruits',
+    fruits: fruits,
+  });
+});
+
+app.get('/fruits/:name', function (req, res) {
+  res.render('fruits/details-layoutsDir', {
+    fruit: req.params.name,
+  });
+});
+
+app.get('/veggies', function (req, res) {
+  res.render('veggies', {
+    title: 'My favorite veggies',
+    veggies: veggies,
+    layout: 'veggie',
+  });
+});
+
+app.get('/veggies/explicit-dir', function (req, res) {
+  res.render('veggies', {
+    title: 'My favorite veggies',
+    veggies: veggies,
+    layout: relative('views/layout/veggie'),
+  });
+});
+
+app.get('/veggies/:name', function (req, res) {
+  res.render('veggies/details', {
+    veggie: req.params.name,
+    layout: 'veggie-details',
+  });
+});
+
+if (require.main === module) {
+  app.listen(3000);
+  console.log('Express server listening on port 3000');
+} else {
+  module.exports = app;
+}

package/.claude/worktrees/security-patches-review-c621ea/example/app.js

@@ -0,0 +1,103 @@
+'use strict';
+// pnpm add express express-hbs
+
+function create(hbs, env) {
+  if (env) process.env.NODE_ENV = env;
+
+  var express = require('express');
+  var app = express();
+  var fs = require('fs');
+  var fp = require('path');
+
+  function relative(path) {
+    return fp.join(__dirname, path);
+  }
+
+  var viewsDir = relative('views');
+
+  app.use(express.static(relative('public')));
+
+  // Hook in express-hbs and tell it where known directories reside
+  app.engine(
+    'hbs',
+    hbs.express4({
+      partialsDir: [relative('views/partials'), relative('views/partials-other')],
+      defaultLayout: relative('views/layout/default.hbs'),
+      restrictLayoutsTo: viewsDir,
+    }),
+  );
+  app.set('view engine', 'hbs');
+  app.set('views', viewsDir);
+
+  // Register sync helper
+  hbs.registerHelper('link', function (text, options) {
+    var attrs = [];
+    for (var prop in options.hash) {
+      attrs.push(prop + '="' + options.hash[prop] + '"');
+    }
+    return new hbs.SafeString('<a ' + attrs.join(' ') + '>' + text + '</a>');
+  });
+
+  // Register Async helpers
+  hbs.registerAsyncHelper('readFile', function (filename, cb) {
+    fs.readFile(fp.join(viewsDir, filename), 'utf8', function (err, content) {
+      if (err) console.error(err);
+      cb(new hbs.SafeString(content));
+    });
+  });
+
+  var fruits = [{ name: 'apple' }, { name: 'orange' }, { name: 'pear' }];
+
+  var veggies = [{ name: 'asparagus' }, { name: 'carrot' }, { name: 'spinach' }];
+
+  app.get('/', function (req, res) {
+    res.render('index', {
+      title: 'express-hbs example',
+    });
+  });
+
+  app.get('/replace', function (req, res) {
+    res.render('replace', {
+      title: 'express-hbs example',
+    });
+  });
+
+  app.get('/fruits', function (req, res) {
+    res.render('fruits/index', {
+      title: 'My favorite fruits',
+      fruits: fruits,
+    });
+  });
+
+  app.get('/fruits/:name', function (req, res) {
+    res.render('fruits/details', {
+      fruit: req.params.name,
+    });
+  });
+
+  app.get('/veggies', function (req, res) {
+    res.render('veggies', {
+      title: 'My favorite veggies',
+      veggies: veggies,
+      layout: 'layout/veggie',
+    });
+  });
+
+  app.get('/veggies/:name', function (req, res) {
+    res.render('veggies/details', {
+      veggie: req.params.name,
+      layout: 'layout/veggie-details',
+    });
+  });
+
+  return app;
+}
+
+if (require.main === module) {
+  var hbs = require('..');
+  var app = create(hbs);
+  app.listen(3000);
+  console.log('Express server listening on port 3000');
+} else {
+  exports.create = create;
+}

package/.claude/worktrees/security-patches-review-c621ea/example/public/css/style.css

@@ -0,0 +1,17 @@
+* {
+  font-family: Georgia, serif;
+}
+
+h1, h2 {
+  font-family: Helvetica, Arial, sans;
+}
+
+.veggie-details {
+    border: 5px solid green;
+    padding: 10px;
+}
+
+.fruit-details {
+    border: 5px solid red;
+    padding: 10px;
+}

package/.claude/worktrees/security-patches-review-c621ea/example/views/fruits/details-layoutsDir.hbs

@@ -0,0 +1,3 @@
+{{!< fruit-details}}
+
+{{fruit}}

package/.claude/worktrees/security-patches-review-c621ea/example/views/fruits/details.hbs

@@ -0,0 +1,4 @@
+{{!< ../layout/fruit-details}}
+
+{{fruit}}
+

package/.claude/worktrees/security-patches-review-c621ea/example/views/fruits/index-layoutsDir.hbs

@@ -0,0 +1,20 @@
+<!-- name of layout -->
+{{!< fruits}}
+
+{{#contentFor 'pageStyles'}}
+<style>
+  li a {
+    color: #800;
+  }
+</style>
+{{/contentFor}}
+
+
+<h1>{{title}}</h1>
+<ul>
+    {{#each fruits}}
+      <li>
+        <a href="/fruits/{{this.name}}">{{this.name}}</a>
+      </li>
+    {{/each}}
+</ul>