@changke/staticnext-build 0.26.1 → 0.27.0

package/AGENTS.md

@@ -0,0 +1,195 @@
+# AGENTS.md
+
+Guidelines for AI agents working in the `@changke/staticnext-build` repository.
+
+## Project Overview
+
+Node.js CLI build tool (`sn-build`) that orchestrates static asset builds: cleaning,
+copying, Markdown-to-HTML, HTML prototyping (Nunjucks or jstmpl), JS/TS bundling,
+and CSS bundling via esbuild. Pure JavaScript, ESM-only, no TypeScript compiler,
+no React/Next.js framework.
+
+## Build / Lint / Test Commands
+
+```bash
+# Lint (ESLint v9 flat config with @stylistic)
+npm run lint
+
+# Run all tests (Node.js built-in test runner, requires Node >= 22.14.0)
+npm test
+
+# Run a single test file
+node --test test/util.test.mjs
+
+# Run tests matching a name pattern
+node --test --test-name-pattern="getTargetPathString" test/util.test.mjs
+
+# Lint + test (runs automatically before npm publish)
+npm run prepublishOnly
+```
+
+There is no build/compile step -- the source is plain `.mjs` files executed directly.
+
+## Module System
+
+- **ESM only.** Package has `"type": "module"`. All files use `.mjs` extension.
+- No CommonJS (`require`, `module.exports`) anywhere.
+
+## Code Style
+
+Formatting is enforced entirely by ESLint with `@stylistic/eslint-plugin` -- there
+is no Prettier. Run `npm run lint` to check.
+
+### Formatting Rules
+
+| Rule | Setting |
+|------|---------|
+| Indentation | 2 spaces |
+| Quotes | Single quotes |
+| Semicolons | Always required |
+| Trailing commas | Never (`comma-dangle: never`) |
+| Object braces | No spaces (`{foo}` not `{ foo }`) |
+| Block spacing | No spaces (`{return x}` not `{ return x }`) |
+| Brace style | 1TBS (opening brace on same line) |
+| Arrow parens | As-needed (omit for single param) |
+| Named function parens | No space before: `function foo()` |
+| Async arrow | Space required: `async () =>` |
+| Line endings | LF only |
+| Trailing whitespace | Trimmed (except in `.md` files) |
+| Final newline | Always insert |
+
+### Import Conventions
+
+```js
+// Node built-ins: always use `node:` prefix
+import {readFile} from 'node:fs/promises';
+import path from 'node:path';
+import {env} from 'node:process';
+
+// Third-party: bare specifiers
+import {build} from 'esbuild';
+import {marked} from 'marked';
+
+// Local: relative paths with explicit .mjs extension
+import {consoleLogColored} from '../utils.mjs';
+import Config from './config.mjs';
+```
+
+- Prefer named imports over namespace imports.
+- Default imports are used for classes/singletons (e.g., `Config`, `path`).
+- Group imports: Node built-ins first, then third-party, then local (separated by blank lines).
+
+### Export Conventions
+
+Modules typically provide both named and default exports:
+
+```js
+const clean = async dirs => { /* ... */ };
+export {clean};
+export default clean;
+```
+
+### Naming Conventions
+
+| Entity | Convention | Examples |
+|--------|-----------|----------|
+| Variables, functions, params | camelCase | `getTargetPathString`, `srcPaths` |
+| Classes | PascalCase | `Config` |
+| Constants | camelCase (not SCREAMING_SNAKE) | `taskName`, `defaultConfig` |
+| Files | kebab-case with `.mjs` | `set-env-dev.mjs`, `is-prod.mjs` |
+| Test files | `*.test.mjs` | `util.test.mjs`, `config.test.mjs` |
+
+### Types
+
+No TypeScript compiler is used. Types are defined via **JSDoc** in `lib/typedefs.mjs`:
+
+```js
+/**
+ * @typedef {Object} PathPart
+ * @property {string} assets Path for general static assets
+ * @property {string=} css Path for CSS files
+ */
+```
+
+Use `@param`, `@returns`, `@typedef`, and `@type` annotations for documenting
+function signatures and inline type hints:
+
+```js
+/** @type string[] */
+const negativePatterns = [];
+```
+
+### Error Handling
+
+- Use `try/catch` in async functions.
+- Log errors with `console.error()`.
+- Top-level entry point (`build.mjs`) catches with `.catch()` and calls `process.exit(1)`.
+- Inner functions log errors and allow graceful continuation where appropriate.
+
+### Async Patterns
+
+- `async/await` is the primary pattern.
+- `Promise.all()` for parallel operations (e.g., running styles + scripts + markdown concurrently).
+- `.then()` chaining for sequential task pipelines:
+  ```js
+  setEnvDev().then(tasks.clean).then(tasks.copy).then(paraDev);
+  ```
+- Arrow functions are the dominant function style.
+
+## Testing
+
+Tests use the **Node.js built-in test runner** (`node:test` module), not Jest or Vitest.
+
+### Test Structure
+
+```js
+import {suite, test} from 'node:test';
+import assert from 'node:assert/strict';
+
+void suite('SuiteName', () => {
+  test('descriptive test name', () => {
+    assert.strictEqual(actual, expected);
+  });
+
+  test('async test', async () => {
+    const result = await someAsyncFunc();
+    assert.strictEqual(result, expected);
+  });
+});
+```
+
+Key patterns:
+- Suites are wrapped with `void suite(...)` (the `void` suppresses the return value).
+- Use `node:assert/strict` -- always strict assertions.
+- Tests clean up after themselves (create/remove temp directories in `before`/`after`).
+- Test fixtures live in `test/fixtures/`.
+
+## Project Structure
+
+```
+build.mjs              CLI entry point (bin: sn-build)
+sn-config.mjs          Default project configuration
+lib/
+  config.mjs           Config loading, merging, path helpers
+  is-prod.mjs          NODE_ENV check helper
+  typedefs.mjs         JSDoc type definitions
+  utils.mjs            File I/O, glob helpers, console coloring
+  vars.mjs             Default configuration values
+  tasks/
+    clean.mjs          Remove target directories
+    copy.mjs           Copy static assets via glob
+    markdown.mjs       Convert .md -> .html (marked + nunjucks/jstmpl)
+    prototype.mjs      Generate static HTML pages from templates
+    scripts.mjs        Bundle JS/TS via esbuild
+    set-env-dev.mjs    Set NODE_ENV=development
+    set-env-prod.mjs   Set NODE_ENV=production
+    styles.mjs         Bundle CSS via esbuild
+test/
+  *.test.mjs           Test files
+  fixtures/            Test fixture data
+```
+
+## Changelog & Versioning
+
+The project follows [Semantic Versioning](https://semver.org/) and maintains a
+`CHANGELOG.md` in [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format.

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.27.0
+2026-02-12
+### Changed
+- Updated dependencies
+- Various code changes after AI (Opus 4.6) code review
+
 ## 0.26.0
 2025-12-21
 ### Removed

package/build.mjs

@@ -3,7 +3,7 @@ import {argv} from 'node:process';
 import path from 'node:path';
 
 import './lib/typedefs.mjs';
-import Config from './lib/config.mjs';
+import config from './lib/config.mjs';
 
 import clean from './lib/tasks/clean.mjs';
 import copy from './lib/tasks/copy.mjs';
@@ -24,14 +24,14 @@ if (debug) {
 }
 
 // load config data
-const conf = await Config.loadConfig();
+const conf = await config.loadConfig();
 
 const taskEnded = taskName => {
   console.timeEnd(taskName);
 };
 
-const srcPaths = Config.getSourcePaths(conf.sourcePath, path.normalize(conf.sourceRoot));
-const tgtPaths = Config.getTargetPaths(conf.targetPath, path.normalize(conf.targetRoot), conf.targetAssetsRoot);
+const srcPaths = config.getSourcePaths(conf.sourcePath, path.normalize(conf.sourceRoot));
+const tgtPaths = config.getTargetPaths(conf.targetPath, path.normalize(conf.targetRoot), conf.targetAssetsRoot);
 
 // Set parameters of each task
 const tasks = {
@@ -47,7 +47,7 @@ const tasks = {
     // Markdown file assets
     // src/main/webapp/md/google-pixel-9/assets/cover.webp -> public/posts/google-pixel-9/assets/cover.webp
     {sources: `${srcPaths.markdown}/**/assets/**/*.*`, target: tgtPaths.markdown, opts: {levelRemoval: 4}}
-  ].concat(Config.getCopyPairs(conf.copyPairs, conf.sourceRoot, tgtPaths.assets))),
+  ].concat(config.getCopyPairs(conf.copyPairs, conf.sourceRoot, tgtPaths.assets))),
   markdown: () => markdown(
     srcPaths.markdown,
     [srcPaths.prototype, srcPaths.modules],
@@ -70,7 +70,7 @@ const tasks = {
     conf.njkGlobals,
     tgtPaths.prototype
   ),
-  scripts: () => scripts(Config.getScriptEntries(conf.moduleEntries, conf.mainEntryFile, srcPaths), tgtPaths.assets),
+  scripts: () => scripts(config.getScriptEntries(conf.moduleEntries, conf.mainEntryFile, srcPaths), tgtPaths.assets),
   styles: () => styles([
     `${srcPaths.css}/brands/*.css`,
     `${srcPaths.css}/index.css`,
@@ -120,6 +120,11 @@ const taskMap = {
 
 const task = taskMap[taskName];
 
+if (typeof task !== 'function') {
+  console.warn(`Task "${taskName}" not found or is not a function!`);
+  process.exit(1);
+}
+
 consoleLogColored('+++ SN Build +++', ['bold', 'blue']);
 console.time(taskName);
 console.log(`Task "${taskName}" started...`);

package/lib/config.mjs

@@ -14,7 +14,7 @@ class Config {
       const cf = configFile || `${cwd()}${this.customConfigFile}`;
       const mod = await import(cf);
       const customConf = mod.default;
-      return this.deepMergeConfObj(defaultConf, customConf);
+      return this.mergeConfObj(defaultConf, customConf);
     } catch (e) {
       // file not exist
       console.error('Error loading file: ', e);
@@ -22,9 +22,9 @@ class Config {
     }
   }
 
-  // keep nested obj values while merging
+  // keep nested obj values while merging (only merges one level deep)
   // e.g. {foo:{a:1,b:2}} merged with {foo:{b:3,c:4}} will be {foo:{a:1,b:3,c:4}}
-  deepMergeConfObj(defaultConf, customConf) {
+  mergeConfObj(defaultConf, customConf) {
     const conf = Object.assign({}, defaultConf);
     for (const [k, v] of Object.entries(customConf)) {
       if (this.objsToMerge.includes(k)) {
@@ -89,12 +89,13 @@ class Config {
    */
   getCopyPairs = (copyPairs, sourceBase, targetBase, appendSourcePath = false) => {
     if (copyPairs && Array.isArray(copyPairs) && copyPairs.length > 0) {
-      return copyPairs.map(pr => {
+      return copyPairs.map(pair => {
+        const pc = {...pair};
         if (appendSourcePath) {
-          pr.sources = `${appendSourcePath}${pr.sources}`;
+          pc.sources = `${sourceBase}${pc.sources}`;
         }
-        pr.target = `${targetBase}${pr.target}`;
-        return pr;
+        pc.target = `${targetBase}${pc.target}`;
+        return pc;
       });
     } else {
       return [];

package/lib/is-prod.mjs

@@ -1,3 +1,5 @@
-export default function() {
-  return (process.env.NODE_ENV === 'production');
-}
+import {env} from 'node:process';
+
+const isProd = () => env.NODE_ENV === 'production';
+
+export default isProd;

package/lib/tasks/copy.mjs

@@ -27,13 +27,10 @@ const globCopy = async (globPatterns, targetRoot, opts, verbose = false) => {
   /** @type string[] */
   const sources = await glob2Array(globPatterns);
 
-  let targetPath = '';
   return Promise.all(sources.map(async src => {
-    if (opts.flat) {
-      targetPath = path.join(targetRoot, path.basename(src));
-    } else {
-      targetPath = path.join(targetRoot, genTargetPath(src, opts.levelRemoval));
-    }
+    const targetPath = opts.flat
+      ? path.join(targetRoot, path.basename(src))
+      : path.join(targetRoot, genTargetPath(src, opts.levelRemoval));
     if (verbose) {
       consoleLogColored(`copying ${src} -> ${targetPath}`, 'dim');
     }

package/lib/tasks/markdown.mjs

@@ -7,18 +7,16 @@ import njk from 'nunjucks';
 import {renderPageToString} from '@changke/jstmpl';
 import {createAndWriteToFile, getTargetPathString, glob2Array, consoleLogColored, isDebugMode} from '../utils.mjs';
 
-marked.use({
-  headerIds: false,
-  mangle: false
-},
-markedXhtml(),
-markedHighlight({
-  langPrefix: 'hljs language-',
-  highlight: (code, lang) => {
-    const language = hljs.getLanguage(lang) ? lang : 'plaintext';
-    return hljs.highlight(code, {language}).value;
-  }
-}));
+marked.use(
+  markedXhtml(),
+  markedHighlight({
+    langPrefix: 'hljs language-',
+    highlight: (code, lang) => {
+      const language = hljs.getLanguage(lang) ? lang : 'plaintext';
+      return hljs.highlight(code, {language}).value;
+    }
+  })
+);
 
 const {Environment, FileSystemLoader} = njk;
 

package/lib/tasks/set-env-dev.mjs

@@ -1,8 +1,5 @@
-const setEnvDev = () => {
-  return new Promise(resolve => {
-    process.env.NODE_ENV = 'development';
-    resolve();
-  });
+const setEnvDev = async () => {
+  process.env.NODE_ENV = 'development';
 };
 
 export default setEnvDev;

package/lib/tasks/set-env-prod.mjs

@@ -1,8 +1,5 @@
-const setEnvProd = () => {
-  return new Promise(resolve => {
-    process.env.NODE_ENV = 'production';
-    resolve();
-  });
+const setEnvProd = async () => {
+  process.env.NODE_ENV = 'production';
 };
 
 export default setEnvProd;

package/lib/tasks/styles.mjs

@@ -20,7 +20,7 @@ const styles = (sources, targetPath, external = []) => {
       outdir: targetPath,
       sourcemap: !isEnvProd(),
       minify: isEnvProd(),
-      external: external
+      external
     });
   });
 };

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@changke/staticnext-build",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "description": "Build scripts extracted from StaticNext seed project",
   "main": "index.js",
   "scripts": {
     "lint": "eslint . lib test",
-    "test": "node --test",
+    "test": "node --test 'test/*.test.mjs'",
     "prepublishOnly": "npm run lint && npm run test"
   },
   "engines": {
@@ -20,15 +20,15 @@
   "type": "module",
   "devDependencies": {
     "@eslint/js": "^9.39.2",
-    "@stylistic/eslint-plugin": "^5.6.1",
+    "@stylistic/eslint-plugin": "^5.8.0",
     "eslint": "^9.39.2",
     "globals": "^16.5.0"
   },
   "dependencies": {
     "@changke/jstmpl": "^0.0.1",
-    "esbuild": "^0.27.2",
+    "esbuild": "^0.27.3",
     "highlight.js": "^11.11.1",
-    "marked": "^17.0.1",
+    "marked": "^17.0.2",
     "marked-highlight": "^2.2.3",
     "marked-xhtml": "^1.0.14",
     "nunjucks": "^3.2.4"