create-node-lib 2.9.13 → 2.10.0

package/AGENTS.md

@@ -0,0 +1,106 @@
+# AGENTS.md
+
+## Project Overview
+
+**create-node-lib** is a scaffolding CLI tool that generates batteries-included Node.js library projects. Users run `npx create-node-lib my-lib-name` (or `pnpm create node-lib my-lib-name`), answer interactive prompts, and get a fully configured project with TypeScript, testing, linting, CI/CD, changesets, and git hooks.
+
+## Architecture
+
+The project has two distinct layers:
+
+### 1. Generator (root level)
+
+The scaffolding engine that prompts users and generates projects:
+
+- **`bin/cli.js`** — CLI entry point. Resolves the generator root and output directory, then delegates to Sao.
+- **`saofile.js`** — Generator definition. Contains prompts, template data helpers, file actions, and post-generation hooks (git init, npm install, husky setup).
+- **`__tests__/generator.test.js`** — Jest tests that use `sao.mock()` to verify generated file lists and content.
+
+### 2. Template (`template/` directory)
+
+The EJS template files that become the generated project. These use placeholders like `<%= projectName %>`, `<%= author %>`, `<%= email %>`, `<%= username %>`, `<%= projectRepository %>`, and helpers like `<%= npmClientInstall(npmClient) %>` and `<%- changesetRepo({ projectRepository }) %>`.
+
+The generated project includes:
+- TypeScript source in `src/` with dual ESM/CJS output via tsup
+- Node.js built-in test runner with c8 coverage
+- ESLint (neostandard) + eslint-plugin-security + Prettier
+- Changesets for versioning and releases
+- Husky git hooks with conventional commits
+- GitHub Actions workflows for CI, releases, link checking, and more
+
+## Tech Stack
+
+| Layer     | Technology                                                    |
+|-----------|---------------------------------------------------------------|
+| Scaffolding | Sao v1.7.1                                                 |
+| Validation  | validate-npm-package-name                                  |
+| Testing     | Jest 29 (generator), Node.js test runner + c8 (template)   |
+| Linting     | ESLint (standard config for generator, neostandard for template) |
+| Formatting  | Prettier                                                    |
+| Releases    | semantic-release (generator), Changesets (template)         |
+| Git hooks   | Husky + lint-staged + commitlint/validate-conventional-commit |
+| Language    | JavaScript (generator), TypeScript (template)               |
+
+## Commands
+
+### Generator (root)
+
+| Command | Purpose |
+|---------|---------|
+| `npm test` | Run Jest tests |
+| `npm run test:watch` | Jest in watch mode |
+| `npm run lint` | ESLint + lockfile-lint |
+| `npm run lint:fix` | ESLint with auto-fix |
+| `npm run format` | Prettier on all JS files |
+
+### Template (generated project)
+
+| Command | Purpose |
+|---------|---------|
+| `npm run build` | `tsc && tsup` — compile TypeScript to ESM + CJS |
+| `npm test` | `c8 node --import tsx --test` — run tests with coverage |
+| `npm run lint` | ESLint + lockfile-lint + markdownlint |
+| `npm run lint:fix` | ESLint with auto-fix |
+| `npm start` | Run CLI via tsx |
+
+## Code Style
+
+- **Prettier**: 100 char print width, 2-space indent, single quotes, no semicolons, no trailing commas
+- **ESLint**: Standard-style rules (generator uses eslint-config-standard; template uses neostandard)
+- **Security**: eslint-plugin-security is enabled in both layers
+- **Commits**: Conventional commit format enforced via git hooks
+- **CommonJS**: The generator itself (`bin/cli.js`, `saofile.js`, tests) uses CommonJS (`require`/`module.exports`)
+- **ESM + TypeScript**: The template generates ESM-first TypeScript projects
+
+## File Conventions
+
+- Generator source files are plain JavaScript at the root level — no transpilation step
+- Template files in `template/` are EJS templates — be careful not to break `<%= ... %>` and `<%- ... %>` placeholders when editing
+- Test files live in `__tests__/` directories (both generator and template)
+- The template's `package.json` uses EJS interpolation for project metadata fields
+
+## Testing
+
+Generator tests use `sao.mock()` to run the generator with mocked prompt answers and assert on:
+- The generated file list (`stream.fileList`)
+- The content of generated files (`stream.readFile()`)
+- Correct template variable substitution
+
+Run tests before committing: `npm test`
+
+## CI/CD
+
+The generator's CI (`.github/workflows/main.yml`) runs on push and PR:
+- Tests on Node.js 24, Ubuntu
+- On push to `main`, runs `semantic-release` to publish to npm
+
+## Key Considerations for Agents
+
+1. **Two-layer architecture**: Changes to the generator logic go in `saofile.js` or `bin/cli.js`. Changes to what gets generated go in `template/`.
+2. **EJS templates**: Files in `template/` are EJS — angle-bracket placeholders (`<%= %>`, `<%- %>`) are intentional and must be preserved.
+3. **Template helpers**: `templateData` in `saofile.js` defines helper functions (`npmClientInstall`, `changesetRepo`) available in templates.
+4. **Sao framework**: The generator uses Sao v1 — refer to Sao v1 docs for the `prompts`, `actions`, `completed` lifecycle.
+5. **No TypeScript at root**: The generator itself is plain JavaScript with CommonJS modules. Only the template output is TypeScript.
+6. **Test with mocks**: Generator tests don't actually create files on disk — they use `sao.mock()` to simulate generation.
+7. **Lockfile-lint**: Both the generator and template validate lockfiles — if you change the package manager config, update the lint:lockfile script accordingly.
+8. **Package managers**: The supported package managers are pnpm (default/recommended) and npm. Yarn is not supported. The `saofile.js` `actions()` handler dynamically sets the `lint:lockfile` script to use `pnpm-lock.yaml` or `package-lock.json` based on the user's choice.

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+# [2.10.0](https://github.com/lirantal/create-node-lib/compare/v2.9.14...v2.10.0) (2026-03-09)
+
+
+### Bug Fixes
+
+* migration to pnpm in workflows ([e6168a4](https://github.com/lirantal/create-node-lib/commit/e6168a498a62f8ab0bb94ec0e38106f3395d37f4))
+* secure defaults for pnpm and npm config and up to date Node.js version ([dc97ca3](https://github.com/lirantal/create-node-lib/commit/dc97ca3f5929711e780a67842620dea7e5be44ea))
+
+
+### Features
+
+* add devcontainer support ([ac2bd5e](https://github.com/lirantal/create-node-lib/commit/ac2bd5e662368bab6e5a7df0c9d1f6ec4a919fbd))
+* move out yarn, add in pnpm ([e6c4e0e](https://github.com/lirantal/create-node-lib/commit/e6c4e0e54bf801dd1e4c1e387ccc0f8506e4a546))
+* update versions for actions and deps ([0deb50c](https://github.com/lirantal/create-node-lib/commit/0deb50ceb7b2560143994645b6cb01e97139bef3))
+
+## [2.9.14](https://github.com/lirantal/create-node-lib/compare/v2.9.13...v2.9.14) (2026-03-09)
+
+
+### Bug Fixes
+
+* Modify automerge.yml to add 'dependencies' label ([d169a3a](https://github.com/lirantal/create-node-lib/commit/d169a3abaa4e9831d522a7a0509a1badc12e77c2))
+
 ## [2.9.13](https://github.com/lirantal/create-node-lib/compare/v2.9.12...v2.9.13) (2026-03-08)
 
 

package/README.md

@@ -22,16 +22,16 @@ Scaffold a batteries-included Node.js library project with docs, tests, semantic
 
 # Install
 
-Generate a new project for the library by running one of the following executors built into npm and yarn:
+Generate a new project for the library by running one of the following:
 
 ```bash
 npx create-node-lib my-cool-lib-name
 ```
 
-or if you're using yarn
+or if you're using pnpm
 
 ```bash
-yarn create node-lib my-cool-lib-name
+pnpm create node-lib my-cool-lib-name
 ```
 
 <img alt="Israel Rail API and CLI using npx and npm" src="https://github.com/user-attachments/assets/48ce8c3b-e56f-44a5-9d87-911c34eae43b" />

package/__tests__/generator.test.js

@@ -45,7 +45,7 @@ describe('all the template files are accountable for', () => {
     const mockProjectRepository = 'https://www.github.com/alice/inchains.git'
     const mockScripts = {
       'lint:lockfile':
-        'lockfile-lint --path package-lock.json --validate-https --allowed-hosts npm yarn'
+        'lockfile-lint --path pnpm-lock.yaml --validate-https --allowed-hosts npm'
     }
 
     const stream = await sao.mock(
@@ -72,15 +72,15 @@ describe('all the template files are accountable for', () => {
     expect(pkg.scripts['lint:lockfile']).toEqual(mockScripts['lint:lockfile'])
   })
 
-  test('Generator input creates correct package.json scripts with yarn as client', async () => {
+  test('Generator input creates correct package.json scripts with npm as client', async () => {
     const mockScripts = {
-      'lint:lockfile': 'lockfile-lint --path yarn.lock --validate-https --allowed-hosts npm yarn'
+      'lint:lockfile': 'lockfile-lint --path package-lock.json --validate-https --allowed-hosts npm'
     }
 
     const stream = await sao.mock(
       { generator: template },
       {
-        npmClient: 'yarn'
+        npmClient: 'npm'
       }
     )
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-node-lib",
-  "version": "2.9.13",
+  "version": "2.10.0",
   "description": "Scaffolding out a Node.js library module",
   "bin": "./bin/cli.js",
   "engines": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "lint": "eslint . && npm run lint:lockfile",
-    "lint:lockfile": "lockfile-lint --path package-lock.json --type npm --validate-https --allowed-hosts npm yarn",
+    "lint:lockfile": "lockfile-lint --path package-lock.json --type npm --validate-https --allowed-hosts npm",
     "lint:fix": "eslint . --fix",
     "format": "prettier --config .prettierrc.js --write '**/*.js'",
     "test": "jest",

package/saofile.js

@@ -1,14 +1,14 @@
 'use strict'
 const validateNpmPackageName = require('validate-npm-package-name')
 
-const SUPPORTED_NPM_CLIENTS = ['npm', 'yarn']
+const SUPPORTED_NPM_CLIENTS = ['pnpm', 'npm']
 
 module.exports = {
   description: 'Scaffolding out a node library.',
   templateData: {
     year: new Date().getFullYear(),
     npmClientInstall: ({ npmClient }) => {
-      return npmClient === 'npm' ? 'install' : 'add'
+      return npmClient === 'pnpm' ? 'add' : 'install'
     },
     changesetRepo: ({ projectRepository }) => {
       // Extract owner/repo from URL like https://github.com/username/reponame
@@ -23,7 +23,7 @@ module.exports = {
       {
         name: 'npmClient',
         message: 'Which package manager do you want to use?',
-        default: 'npm',
+        default: 'pnpm',
         type: 'list',
         choices: SUPPORTED_NPM_CLIENTS
       },
@@ -84,7 +84,7 @@ module.exports = {
     ]
   },
   actions() {
-    const lockfile = this.answers.npmClient === 'npm' ? 'package-lock.json' : 'yarn.lock'
+    const lockfile = this.answers.npmClient === 'pnpm' ? 'pnpm-lock.yaml' : 'package-lock.json'
     return [
       {
         type: 'add',
@@ -97,7 +97,7 @@ module.exports = {
         handler(data, filepath) {
           data.scripts[
             'lint:lockfile'
-          ] = `lockfile-lint --path ${lockfile} --validate-https --allowed-hosts npm yarn`
+          ] = `lockfile-lint --path ${lockfile} --validate-https --allowed-hosts npm`
           return data
         }
       }

package/template/.devcontainer/devcontainer.json

@@ -0,0 +1,28 @@
+{
+    "name": "Project Devcontainer",
+    "image": "mcr.microsoft.com/devcontainers/typescript-node:24-bookworm",
+    "mounts": [
+        "source=${localEnv:HOME}/.gitconfig,target=/home/node/.gitconfig,type=bind,consistency=cached"
+    ],
+    // Initialize access to 1Password CLI in the container
+	// "initializeCommand": "echo OP_SERVICE_ACCOUNT_TOKEN=$(op read 'op://Private/1Password op CLI Service Account for DevContainers/password') > .env.development",
+	// "runArgs": [
+	// 	"--env-file",
+	// 	"${localWorkspaceFolder}/.env.development"
+	// ],
+    // --
+    "postCreateCommand": {
+        "git-setup": "git config --local commit.gpgsign false; git config --local core.pager \"less -R\";",
+        "pnpm-install": "pnpm install --force",
+        "post-create": "bash .devcontainer/post-create.sh"
+    },
+    "postStartCommand": {
+        // "rm-env-file": "rm -f ./.env.development",
+        "start-dev": "pnpm run dev"
+    },
+    "remoteUser": "node",
+    "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
+    "containerEnv": {
+        "NODE_ENV": "development"
+    }
+}

package/template/.devcontainer/post-create.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+set -e
+
+# Install OpenCode CLI
+# curl -fsSL https://opencode.ai/install | bash
+
+# Install Snyk CLI
+# curl --compressed https://static.snyk.io/cli/latest/snyk-linux-arm64 -o snyk
+# chmod +x ./snyk
+# sudo mv -f ./snyk /usr/local/bin/snyk
+
+# Install 1Password CLI (op) - arm64 Linux binary
+# OP_VERSION="2.32.1"
+# curl -fsSL "https://cache.agilebits.com/dist/1P/op2/pkg/v${OP_VERSION}/op_linux_arm64_v${OP_VERSION}.zip" -o /tmp/op.zip
+# python3 -c "import zipfile; zipfile.ZipFile('/tmp/op.zip').extract('op', '/tmp')"
+# sudo mv /tmp/op /usr/local/bin/op && chmod +x /usr/local/bin/op && rm /tmp/op.zip

package/template/.github/workflows/automerge.yml

@@ -16,10 +16,12 @@ on:
   check_suite:
     types:
       - completed
-  status: {}
 jobs:
   automerge:
     runs-on: ubuntu-latest
+    if: >
+      github.event_name != 'check_suite' ||
+      github.event.check_suite.pull_requests[0] != null
     permissions:
       contents: write
       pull-requests: write
@@ -30,10 +32,10 @@ jobs:
         env:
           GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
           # we only merge PRs with labels of "dependencies" 
-          MERGE_LABELS: "automerge"
+          MERGE_LABELS: "automerge,dependencies"
           MERGE_REMOVE_LABELS: "automerge"
           MERGE_METHOD: "squash"
           MERGE_COMMIT_MESSAGE: "automatic"
           MERGE_FORKS: "false"
           MERGE_REQUIRED_APPROVALS: "0"
-          UPDATE_METHOD: "rebase"
+          UPDATE_METHOD: "rebase"

package/template/.github/workflows/ci.yml

@@ -11,18 +11,20 @@ jobs:
     name: Node v${{matrix.node}} ((${{matrix.platform}}))
     runs-on: ${{matrix.platform}}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v6
         with:
           node-version: ${{matrix.node}}
+          cache: 'pnpm'
       - name: install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
       - name: lint code
-        run: npm run lint
+        run: pnpm run lint
       - name: build project
-        run: npm run build
+        run: pnpm run build
       - name: run tests
-        run: npm run test
+        run: pnpm run test
       - name: coverage
         uses: codecov/codecov-action@v5
         if: github.actor != 'dependabot[bot]'
@@ -37,13 +39,15 @@ jobs:
     runs-on: ubuntu-latest
     needs: test
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v6
         with:
           node-version: "22.x"
+          cache: 'pnpm'
       - name: install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
       - name: build project
-        run: npm run build
+        run: pnpm run build
       - name: release preview with pkr-pr-new
-        run: npx pkg-pr-new publish
+        run: pnpx pkg-pr-new publish

package/template/.github/workflows/links-checker-schedule.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           persist-credentials: false
 

package/template/.github/workflows/lock-threads.yml

@@ -14,7 +14,7 @@ jobs:
   stale:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/stale@28ca1036281a5e5922ead5184a1bbf96e5fc984e # v9.0.0
+      - uses: actions/stale@b5d41d4e1d5dceea10e7104786b73624c18a190f # v10.2.0
         with:
           close-issue-message: |
             This issue has not seen any activity since it was marked stale.

package/template/.github/workflows/markdown-lint.yml

@@ -11,13 +11,19 @@ jobs:
     name: Lint Markdown files
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v4
 
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
           node-version: '22'
+          cache: 'pnpm'
+
+      - name: install dependencies
+        run: pnpm install --frozen-lockfile
 
       - name: Markdown Lint
         run: |
-          npm run lint:markdown || npx -y markdownlint-cli@0.45.0 -c .github/.markdownlint.yml -i '.git' -i '__tests__' -i '.github' -i '.changeset' -i 'CODE_OF_CONDUCT.md' -i 'CHANGELOG.md' -i 'node_modules' -i 'dist' '**/**.md'
+          pnpm run lint:markdown || pnpx -y markdownlint-cli@0.45.0 -c .github/.markdownlint.yml -i '.git' -i '__tests__' -i '.github' -i '.changeset' -i 'CODE_OF_CONDUCT.md' -i 'CHANGELOG.md' -i 'node_modules' -i 'dist' '**/**.md'

package/template/.github/workflows/release.yml

@@ -19,20 +19,20 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v6
         with:
           node-version: 24.x
-      - name: Update npm
-        run: npm update -g npm          
+          cache: 'pnpm'
       - name: install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
       - name: build project
-        run: npm run build
+        run: pnpm run build
       - name: Create Release Pull Request or Publish to npm
         uses: changesets/action@v1
         with:
-          publish: npm run release
-          version: npm run version
+          publish: pnpm run release
+          version: pnpm run version
           commit: "chore: new release"
           title: "chore: new release candidate"
         env:

package/template/package.json

@@ -26,9 +26,9 @@
     }
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=24.0.0"
   },
-  "packageManager": "npm@8.4.0",
+  "packageManager": "pnpm@10.31.0",
   "files": [
     "dist",
     "src",
@@ -40,7 +40,7 @@
     "lint": "eslint . && npm run lint:lockfile && npm run lint:markdown",
     "lint:markdown": "npx -y markdownlint-cli@0.45.0 -c .github/.markdownlint.yml -i '.git' -i '__tests__' -i '.github' -i '.changeset' -i 'CODE_OF_CONDUCT.md' -i 'CHANGELOG.md' -i 'docs/**' -i 'node_modules' -i 'dist' '**/**.md' --fix",
     "lint:fix": "eslint . --fix",
-    "lint:lockfile": "lockfile-lint --path package-lock.json --validate-https --allowed-hosts npm yarn",
+    "lint:lockfile": "lockfile-lint --path pnpm-lock.yaml --validate-https --allowed-hosts npm",
     "test": "c8 node --import tsx --test __tests__/**/*.test.ts",
     "test:watch": "c8 node --import tsx --test --watch __tests__/**/*.test.ts",
     "coverage:view": "open coverage/lcov-report/index.html",
@@ -72,14 +72,14 @@
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.0",
     "@changesets/cli": "^2.27.7",
-    "@types/node": "^20.14.10",
+    "@types/node": "^24.10.1",
     "c8": "^10.1.2",
     "eslint": "^9.6.0",
     "eslint-plugin-security": "^3.0.1",
     "husky": "^9.0.11",
-    "lint-staged": "^15.2.7",
+    "lint-staged": "^16.2.7",
     "lockfile-lint": "^4.14.0",
-    "neostandard": "^0.11.0",
+    "neostandard": "^0.12.2",
     "tsup": "^8.1.0",
     "tsx": "^4.19.4",
     "typescript": "^5.5.3",

package/template/pnpm-workspace.yaml

@@ -0,0 +1,14 @@
+# Source for more information: https://github.com/lirantal/npm-security-best-practices
+
+# Fail if a package's trust level has decreased (pnpm 10.21+)
+trustPolicy: no-downgrade
+
+# Allow specific packages or versions to bypass the check when needed
+# example:
+#trustPolicyExclude:
+#  - 'chokidar@4.0.3'
+#  - 'webpack@4.47.0 || 5.102.1'
+
+# Ignore the check for packages published more than 30 days ago (pnpm 10.27+)
+# Useful for older packages that pre-date provenance support
+trustPolicyIgnoreAfter: 43200  # minutes (30 days)