express-hbs 2.4.2 → 2.5.1

package/.claude/worktrees/node-20-26-migration-7de0c3/.editorconfig

@@ -0,0 +1,8 @@
+; indicate this is the root of the project
+
+[*]
+indent_style = space
+end_of_line = lf
+
+[*.js]
+indent_size = 2

package/.claude/worktrees/node-20-26-migration-7de0c3/.github/workflows/publish.yml

@@ -0,0 +1,73 @@
+name: Publish
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'package.json'
+  workflow_dispatch:
+    inputs:
+      dry-run:
+        description: 'Preview what would be published without actually publishing'
+        required: false
+        type: boolean
+        default: true
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  publish:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+
+    permissions:
+      # OIDC trusted publishing to npm. Provenance is enabled because this
+      # repository is public; public repos can generate a provenance
+      # attestation at publish time.
+      id-token: write
+      contents: read
+
+    env:
+      FORCE_COLOR: 1
+      CI: true
+      NPM_CONFIG_PROVENANCE: true
+      NPM_CONFIG_REGISTRY: 'https://registry.npmjs.org'
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
+        with:
+          node-version: '26.13.0'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install Corepack
+        run: npm install --global corepack@0.34.6
+      - name: Enable corepack
+        run: corepack enable
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --prefer-offline
+
+      - name: Determine whether to publish
+        id: pub
+        run: |
+          name=$(jq -r .name package.json)
+          version=$(jq -r .version package.json)
+          if [ -n "$(npm view "$name@$version" version 2>/dev/null)" ]; then
+            echo "$name@$version is already published; nothing to do"
+            echo "publish=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "queueing $name@$version"
+            echo "publish=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Publish to npm
+        if: steps.pub.outputs.publish == 'true'
+        # --no-git-checks is required because actions/checkout leaves the repo on
+        # a detached HEAD, which pnpm's default publish branch check rejects.
+        run: pnpm publish --no-git-checks ${{ (github.event.inputs['dry-run'] == 'true' && '--dry-run') || '' }}

package/.claude/worktrees/node-20-26-migration-7de0c3/.github/workflows/test.yml

@@ -0,0 +1,48 @@
+name: Test
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [22, 24, 26]
+    name: Node ${{ matrix.node }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@73e46992e05b19abd31f2f3c20e0e7370d762115 # v6.1.1
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: ${{ matrix.node }}
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+      - name: Run tests with coverage
+        run: pnpm coverage
+
+  required-checks-pass:
+    name: Required checks pass
+    if: always()
+    needs: [build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Verify all required jobs succeeded
+        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
+        run: exit 1

package/.claude/worktrees/node-20-26-migration-7de0c3/.jsbeautifyrc

@@ -0,0 +1,17 @@
+{
+    "indent_size": 2,
+    "indent_char": " ",
+    "indent_level": 0,
+    "indent_with_tabs": false,
+    "preserve_newlines": true,
+    "max_preserve_newlines": 10,
+    "jslint_happy": false,
+    "brace_style": "collapse",
+    "keep_array_indentation": false,
+    "keep_function_indentation": false,
+    "space_before_conditional": true,
+    "break_chained_methods": false,
+    "eval_code": false,
+    "unescape_strings": false,
+    "wrap_line_length": 0
+}

package/.claude/worktrees/node-20-26-migration-7de0c3/.nvmrc

@@ -0,0 +1 @@
+22

package/.claude/worktrees/node-20-26-migration-7de0c3/.nycrc.json

@@ -0,0 +1,16 @@
+{
+  "all": true,
+  "include": [
+    "index.js",
+    "lib/**/*.js"
+  ],
+  "branches": 80,
+  "functions": 80,
+  "lines": 80,
+  "statements": 80,
+  "reporter": [
+    "text",
+    "json-summary",
+    "lcov"
+  ]
+}

package/.claude/worktrees/node-20-26-migration-7de0c3/.oxfmtrc.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "singleQuote": true,
+  "tabWidth": 2,
+  "sortPackageJson": false,
+  "ignorePatterns": [
+    "**/node_modules/**",
+    "**/coverage/**",
+    "pnpm-lock.yaml",
+    "**/*.json",
+    "**/*.jsonc",
+    "**/*.yml",
+    "**/*.yaml",
+    "**/*.md",
+    "**/*.hbs",
+    "**/*.html",
+    "**/*.css"
+  ]
+}

package/.claude/worktrees/node-20-26-migration-7de0c3/.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/node-20-26-migration-7de0c3/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/node-20-26-migration-7de0c3/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/node-20-26-migration-7de0c3/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/node-20-26-migration-7de0c3/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 🙏.