@nci-gis/js-tmpl 0.0.1-beta.1 → 0.0.1

package/README.md

@@ -1,13 +1,15 @@
 # js-tmpl
 
-> A lightweight, deterministic file templating engine built on Handlebars
+> A lightweight, deterministic file templating engine built on Handlebars.
+>
+> An explicit file templating engine for developers who care about **control, predictability, and composability**.
 
 [![npm version](https://img.shields.io/npm/v/@nci-gis/js-tmpl.svg)](https://www.npmjs.com/package/@nci-gis/js-tmpl)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## What is js-tmpl?
 
-js-tmpl is a **pure transformation layer** that generates files and directory structures from templates with predictable, explicit behavior.
+js-tmpl is a **pure transformation layer** that turns **templates + data → files**, nothing more, nothing less.
 
 It's designed for:
 
@@ -18,17 +20,33 @@ It's designed for:
 
 **Not a framework. Not a workflow tool. Just a focused rendering engine.**
 
+## Is js-tmpl for you?
+
+js-tmpl is a good fit if you:
+
+- embed templating inside other tools or pipelines
+- want **the same input to always produce the same output**
+- prefer explicit configuration over conventions
+- need programmatic control, not just a CLI
+
+It may **not** be a good fit if you want:
+
+- opinionated project generators
+- convention-based magic
+- interactive scaffolding workflows
+
 ## Why js-tmpl?
 
-Most template tools are either too simple (basic string replacement) or too complex (opinionated frameworks). js-tmpl fills the gap:
+Most templating tools fail in one of two ways:
+
+- they are too simple to scale beyond string replacement
+- or too opinionated to embed safely in larger systems
 
-- ✅ **Engine-First**: Programmatic API, CLI is secondary
-- ✅ **Deterministic**: Same input → same output, always
-- ✅ **Explicit**: No magic defaults or hidden conventions
-- ✅ **Composable**: Small, focused layers
-- ✅ **Embeddable**: Designed to integrate into larger tools
+js-tmpl sits intentionally in between.
 
-See [docs/00-Motivation.md](docs/00-Motivation.md) for the full story.
+See [Motivation](docs/Motivation.md) - The full story.
+
+See [Design Principles](docs/PRINCIPLES.md) - Core philosophy guiding all decisions.
 
 ## Features
 
@@ -40,6 +58,52 @@ See [docs/00-Motivation.md](docs/00-Motivation.md) for the full story.
 - 🔒 **No Global State** - Isolated render passes, no pollution
 - 📝 **YAML/JSON Support** - Load values from either format
 
+## Fixed Rules for Minimal Auto-Discovery
+
+js-tmpl follows the principle **"Explicit Over Implicit"** - most configuration must be provided explicitly. However, for developer convenience, exactly **ONE** type of auto-discovery is allowed:
+
+### Project Configuration File (Optional)
+
+js-tmpl will search for a project config file in **exactly these locations**, in this order, relative to the current working directory:
+
+1. `js-tmpl.config.yaml` (highest priority)
+2. `js-tmpl.config.yml`
+3. `js-tmpl.config.json`
+4. `config/js-tmpl.yaml`
+5. `config/js-tmpl.json` (lowest priority)
+
+**First match wins.** If no config file is found, internal defaults are used.
+
+### What is NOT Auto-Discovered
+
+Everything else must be **explicitly specified**:
+
+- ✅ **Values file** - Required via `--values` flag or `valuesFile` config
+- ✅ **Template directory** - Must be in config or defaults to `templates/`
+- ✅ **Output directory** - Must be in config or defaults to `dist/`
+- ✅ **Partials directory** - Must be in config; not loaded if omitted
+
+### Override Auto-Discovery
+
+You can bypass auto-discovery entirely:
+
+```bash
+# Explicit config file (no auto-discovery)
+js-tmpl render --values data.yaml --config-file /path/to/custom-config.yaml
+
+# No config file (use defaults only)
+js-tmpl render --values data.yaml --template-dir ./templates --out ./dist
+```
+
+### Why These Rules?
+
+1. **Predictable** - Fixed search order, no magic
+2. **Minimal** - Only config file location is auto-discovered
+3. **Overridable** - Always use `--config-file` for explicit control
+4. **Documented** - You're reading the complete list right now
+
+**These are the ONLY auto-discovery rules. Nothing else is implicit.**
+
 ## Installation
 
 ```bash
@@ -75,14 +139,9 @@ templates/
 **Template content** (`templates/${project.name}/config.json.hbs`):
 
 ```handlebars
-{
-  "name": "{{project.name}}",
-  "version": "{{project.version}}",
-  "server": {
-    "port": {{config.port}},
-    "host": "{{config.host}}"
-  }
-}
+{ "name": "{{project.name}}", "version": "{{project.version}}", "server": {
+"port":
+{{config.port}}, "host": "{{config.host}}" } }
 ```
 
 ### 3. Render templates
@@ -101,7 +160,7 @@ import { resolveConfig, renderDirectory } from '@nci-gis/js-tmpl';
 const config = resolveConfig({
   valuesFile: './values.yaml',
   templateDir: './templates',
-  outDir: './dist'
+  outDir: './dist',
 });
 
 await renderDirectory(config);
@@ -128,14 +187,11 @@ CLI arguments
 
 ### View Model
 
-Templates receive a view object:
+Templates receive a view object containing your values data plus an `env` object with allowlisted environment variables. The `env` key is reserved — if your values file contains a top-level `env` key, a warning is logged and it is overwritten.
 
-```javascript
-{
-  ...valuesFromFile,  // Your YAML/JSON data
-  env: process.env    // Environment variables
-}
-```
+Use `envKeys` and `envPrefix` in your config file or via CLI (`--env-keys`, `--env-prefix`) to control which environment variables are exposed. Without either, `env` is an empty object `{}`.
+
+See [docs/API.md](docs/API.md#view-object) for full details, examples, and recommended conventions.
 
 Access in templates:
 
@@ -158,21 +214,40 @@ templates/
 
 ### Partial System
 
-**Root partials** (`_name.hbs`):
+Each render pass uses an isolated Handlebars instance. Directory structure maps to partial names:
 
 ```text
 templates.partials/
-└── _header.hbs  → {{> header}}
+├── header.hbs                → {{> header}}
+├── components/
+│   ├── button.hbs           → {{> components.button}}
+│   └── forms/
+│       └── login.hbs        → {{> components.forms.login}}
 ```
 
-**Namespaced partials** (`@group/name.hbs`):
+**`@` directories** flatten their contents (filename only, no namespace):
 
 ```text
-templates.partials/
-└── @common/
-    └── metadata.hbs  → {{> common.metadata}}
+├── @helpers/
+│   └── date.hbs             → {{> date}}
 ```
 
+Duplicate partial names throw an error. Names must be alphanumeric + underscore only. See [API docs](docs/API.md#partial-system) for details.
+
+## Mental Model
+
+> ⚠️ Design note
+> js-tmpl prefers failing loudly over guessing silently.
+
+Think of js-tmpl as a function:
+
+```text
+(input templates, data, config) → output files
+```
+
+There is no hidden state, no lifecycle, and no side effects.
+If you need orchestration, state, or interactivity, build it **around** js-tmpl — not inside it.
+
 ## CLI Reference
 
 ```bash
@@ -181,14 +256,16 @@ js-tmpl render [options]
 
 ### Options
 
-| Option                   | Description             | Default              |
-| ------------------------ | ----------------------- | -------------------- |
-| `-c, --values FILE`      | Values file (YAML/JSON) | **Required**         |
-| `-t, --template-dir DIR` | Template directory      | `templates`          |
-| `-o, --out DIR`          | Output directory        | `dist`               |
-| `-p, --partials-dir DIR` | Partials directory      | `templates.partials` |
-| `-x, --ext EXT`          | Template extension      | `.hbs`               |
-| `--config-file FILE`     | Explicit config file    | Auto-discovered      |
+| Option                   | Description                             | Default         |
+| ------------------------ | --------------------------------------- | --------------- |
+| `-c, --values FILE`      | Values file (YAML/JSON)                 | **Required**    |
+| `-t, --template-dir DIR` | Template directory                      | `templates`     |
+| `-o, --out DIR`          | Output directory                        | `dist`          |
+| `-p, --partials-dir DIR` | Partials directory                      | None (skipped)  |
+| `-x, --ext EXT`          | Template extension                      | `.hbs`          |
+| `--config-file FILE`     | Explicit config file                    | Auto-discovered |
+| `--env-keys KEYS`        | Comma-separated env var names to expose | None            |
+| `--env-prefix PREFIX`    | Auto-include env vars with this prefix  | None            |
 
 ### Examples of Usage
 
@@ -202,79 +279,13 @@ js-tmpl render \
   --template-dir ./my-templates \
   --out ./output
 
-# Multi-environment
-NODE_ENV=production js-tmpl render --values prod-values.yaml
+# Multi-environment (allowlist NODE_ENV to use it in templates)
+NODE_ENV=production js-tmpl render --values prod-values.yaml --env-keys NODE_ENV
 ```
 
 ## Programmatic API
 
-See [docs/API.md](docs/API.md) for comprehensive API documentation.
-
-### Import
-
-```javascript
-import { resolveConfig, renderDirectory } from '@nci-gis/js-tmpl';
-```
-
-### resolveConfig(options)
-
-Resolves configuration with proper precedence.
-
-**Parameters:**
-
-- `options.valuesFile` (string, required) - Path to values file
-- `options.templateDir` (string) - Template directory path
-- `options.partialsDir` (string) - Partials directory path
-- `options.outDir` (string) - Output directory path
-- `options.extname` (string) - Template file extension
-- `options.configFile` (string) - Explicit config file path
-
-**Returns:** Resolved configuration object
-
-### renderDirectory(config)
-
-Executes the rendering process.
-
-**Parameters:**
-
-- `config` (object) - Configuration from `resolveConfig`
-
-**Returns:** Promise that resolves when rendering completes
-
-### Example
-
-```javascript
-import { resolveConfig, renderDirectory } from '@nci-gis/js-tmpl';
-
-const config = resolveConfig({
-  valuesFile: './values.yaml',
-  templateDir: './templates',
-  partialsDir: './partials',
-  outDir: './dist'
-});
-
-await renderDirectory(config);
-console.log('✅ Rendering complete');
-```
-
-## Project Configuration
-
-Create `js-tmpl.config.yaml` in your project root:
-
-```yaml
-templateDir: templates
-partialsDir: templates.partials
-outDir: dist
-extname: .hbs
-```
-
-Auto-discovered config files (in order):
-
-1. `js-tmpl.config.yaml`
-2. `js-tmpl.config.yml`
-3. `js-tmpl.config.json`
-4. `config/js-tmpl.yaml`
-5. `config/js-tmpl.json`
+See [docs/API.md](docs/API.md) for the complete API reference — parameters, return types, config file format, and advanced usage.
 
 ## Examples
 
@@ -287,26 +298,14 @@ See [examples/yaml-templates/](examples/yaml-templates/) for a complete working
 
 ## Testing
 
-This project has comprehensive test coverage:
-
-- 156 tests
-- 99.8% line coverage
-- 99.7% branch coverage
+This project has comprehensive automated test coverage across unit and integration suites.
+Current coverage remains above 99% line coverage with high branch coverage as well.
 
 See [tests/README.md](tests/README.md) for testing documentation.
 
 ## Development Principles
 
-js-tmpl follows strict design principles:
-
-1. **Engine First, CLI Second** - Programmatic API is primary
-2. **Explicit Over Implicit** - No magic or hidden conventions
-3. **Deterministic Over Clever** - Predictable behavior
-4. **Separation of Concerns** - Each layer has one responsibility
-5. **Composable Over Monolithic** - Small, focused functions
-6. **Simple Over Feature-Rich** - Minimal API surface
-
-See [docs/PRINCIPLES.md](docs/PRINCIPLES.md) for details.
+js-tmpl follows six core design principles — engine-first, explicit, deterministic, separated, composable, and simple. See [docs/PRINCIPLES.md](docs/PRINCIPLES.md) for the full philosophy.
 
 ## Roadmap
 
@@ -340,9 +339,18 @@ For security concerns, see [SECURITY.md](SECURITY.md).
 
 MIT © pasxd245
 
-## Links
+## Learn More
+
+### 📚 Documentation
+
+- **[📖 Documentation Hub](docs/ToC.md)** - Complete documentation index with learning paths
+- [Design Principles](docs/PRINCIPLES.md) - Core philosophy guiding all decisions
+- [Workflow Overview](docs/WORKFLOW.md) - Visual diagrams of the rendering pipeline
+- [API Reference](docs/API.md) - Complete programmatic API documentation
+- [Motivation](docs/Motivation.md) - Why js-tmpl exists and our vision
+
+### 🔗 Others
 
-- [Documentation](docs/)
-- [Examples](examples/)
-- [Issue Tracker](https://github.com/nci-gis/js-tmpl/issues)
-- [NPM Package](https://www.npmjs.com/package/@nci-gis/js-tmpl)
+- [Examples](examples/) - Working examples and templates
+- [Issue Tracker](https://github.com/nci-gis/js-tmpl/issues) - Report bugs or request features
+- [NPM Package](https://www.npmjs.com/package/@nci-gis/js-tmpl) - Package registry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nci-gis/js-tmpl",
-  "version": "0.0.1-beta.1",
+  "version": "0.0.1",
   "description": "The pure JavaScript templating engine that uses handlebars.",
   "type": "module",
   "bin": {
@@ -11,6 +11,24 @@
       "import": "./src/index.js"
     }
   },
+  "scripts": {
+    "prepare": "husky",
+    "test": "node --test $(find tests -name '*.test.js')",
+    "test:watch": "node --test --watch $(find tests -name '*.test.js')",
+    "test:coverage": "node --experimental-test-coverage --test $(find tests -name '*.test.js')",
+    "format": "prettier --write src/ tests/",
+    "format:check": "prettier --check src/ tests/",
+    "lint": "eslint src/ tests/",
+    "lint:fix": "eslint src/ tests/ --fix",
+    "build": "echo 'No build step required for pure JS library'",
+    "start": "node src/cli/main.js",
+    "help": "node src/cli/main.js --help",
+    "dev": "node src/cli/main.js",
+    "tool": "node src/cli/main.js",
+    "docs:check-links": "remark --frail --quiet *.md docs/*.md tests/README.md examples/**/*.md",
+    "docs:check-exports": "node scripts/check-doc-exports.js",
+    "docs:check": "pnpm docs:check-links && pnpm docs:check-exports"
+  },
   "keywords": [
     "js",
     "templating",
@@ -37,6 +55,7 @@
     "node": ">=20.0.0",
     "pnpm": ">=10.0.0"
   },
+  "packageManager": "pnpm@10.22.0",
   "dependencies": {
     "config": "^4.1.1",
     "handlebars": "^4.7.8",
@@ -44,19 +63,28 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.5.2",
     "eslint": "^9.39.2",
-    "eslint-plugin-simple-import-sort": "^12.1.1"
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "prettier": "^3.8.1",
+    "remark-cli": "^12.0.1",
+    "remark-validate-links": "^13.1.0",
+    "typescript": "^6.0.2"
   },
-  "scripts": {
-    "test": "node --test $(find tests -name '*.test.js')",
-    "test:watch": "node --test --watch $(find tests -name '*.test.js')",
-    "test:coverage": "node --experimental-test-coverage --test $(find tests -name '*.test.js')",
-    "lint": "eslint src/ tests/",
-    "lint:fix": "eslint src/ tests/ --fix",
-    "build": "echo 'No build step required for pure JS library'",
-    "start": "node src/cli/main.js",
-    "help": "node src/cli/main.js --help",
-    "dev": "node src/cli/main.js",
-    "tool": "node src/cli/main.js"
+  "lint-staged": {
+    "src/**/*.js": [
+      "prettier --write",
+      "eslint --fix"
+    ],
+    "tests/**/*.js": [
+      "prettier --write",
+      "eslint --fix"
+    ],
+    "**/*.md": [
+      "prettier --write"
+    ]
   }
-}
+}

package/src/cli/args.js

@@ -1,49 +1,66 @@
 /**
  * Parse CLI arguments.
- * 
+ *
  * @param {string[]} args
- * @returns {Record<string, any>}
+ * @returns {import('../types.js').CliArgs}
  */
 export function parseArgs(args) {
-  const opts = { command: "render" };
+  /** @type {import('../types.js').CliArgs} */
+  const opts = { command: 'render' };
 
   let i = 0;
   while (i < args.length) {
     const a = args[i];
 
     switch (a) {
-      case "render":
-        opts.command = "render";
+      case '-h':
+      case '--help':
+        opts.command = 'help';
         break;
 
-      case "-t":
-      case "--template-dir":
+      case 'render':
+        opts.command = 'render';
+        break;
+
+      case '-t':
+      case '--template-dir':
         opts.templateDir = args[++i];
         break;
 
-      case "-c":
-      case "--values":
+      case '-c':
+      case '--values':
         opts.valuesFile = args[++i];
         break;
 
-      case "-o":
-      case "--out":
+      case '-o':
+      case '--out':
         opts.outDir = args[++i];
         break;
 
-      case "-p":
-      case "--partials-dir":
+      case '-p':
+      case '--partials-dir':
         opts.partialsDir = args[++i];
         break;
 
-      case "--config-file":
+      case '--config-file':
         opts.configFile = args[++i];
         break;
 
-      case "-x":
-      case "--ext":
+      case '-x':
+      case '--ext':
         opts.extname = args[++i];
         break;
+
+      case '--env-keys':
+        opts.envKeys = args[++i]
+          .split(',')
+          .map((s) => s.trim())
+          .filter(Boolean);
+        break;
+
+      case '--env-prefix':
+        opts.envPrefix = args[++i];
+        break;
     }
     // next argument:
     i++;

package/src/cli/main.js

@@ -1,14 +1,21 @@
 #!/usr/bin/env node
 
-import { resolveConfig } from "../config/resolver.js";
-import { renderDirectory } from "../engine/renderDirectory.js";
-import { parseArgs } from "./args.js";
+import { resolveConfig } from '../config/resolver.js';
+import { renderDirectory } from '../engine/renderDirectory.js';
+import { parseArgs } from './args.js';
+import { USAGE } from './usage.js';
 
+/** @returns {Promise<void>} */
 export async function main() {
   const cli = parseArgs(process.argv);
 
-  if (cli.command !== "render") {
-    console.error("Unknown command:", cli.command);
+  if (cli.command === 'help') {
+    console.log(USAGE);
+    return;
+  }
+
+  if (cli.command !== 'render') {
+    console.error('Unknown command:', cli.command);
     process.exit(1);
   }
 
@@ -16,13 +23,19 @@ export async function main() {
 
   await renderDirectory(cfg);
 
-  console.log("✔ js-tmpl completed.");
+  console.log('✔ js-tmpl completed.');
 }
 
 // Execute main function if this file is run directly
-try {
-  await main();
-} catch (error) {
-  console.error("Error:", error);
-  process.exit(1);
+const isDirectRun =
+  process.argv[1] &&
+  import.meta.url.endsWith(process.argv[1].replaceAll('\\', '/'));
+
+if (isDirectRun) {
+  try {
+    await main();
+  } catch (error) {
+    console.error('Error:', error);
+    process.exit(1);
+  }
 }

package/src/cli/usage.js

@@ -0,0 +1,16 @@
+/** CLI usage text. */
+export const USAGE = `Usage: js-tmpl [command] [options]
+
+Commands:
+  render                     Render templates (default)
+
+Options:
+  -t, --template-dir <dir>   Template directory (default: templates)
+  -c, --values <file>        Values file (YAML or JSON) [required]
+  -o, --out <dir>            Output directory (default: dist)
+  -p, --partials-dir <dir>   Partials directory
+  -x, --ext <ext>            Template extension (default: .hbs)
+      --config-file <file>   Project config file
+      --env-keys <keys>      Comma-separated env var names to expose (default: none)
+      --env-prefix <prefix>  Auto-include env vars with this prefix (e.g. JS_TMPL_)
+  -h, --help                 Show this help message`;

package/src/config/defaults.js

@@ -1,8 +1,10 @@
 export const DEFAULTS = {
-  templateDir: "templates",
-  partialsDir: "templates.partials",
-  valuesDir: "templates.values",
-  valuesFile: "",
-  outDir: "dist",
-  extname: ".hbs",
+  templateDir: 'templates',
+  partialsDir: '',
+  valuesDir: '',
+  valuesFile: '',
+  outDir: 'dist',
+  extname: '.hbs',
+  envKeys: [],
+  envPrefix: '',
 };

package/src/config/loader.js

@@ -1,22 +1,30 @@
-import fs from "node:fs";
-import path from "node:path";
+import fs from 'node:fs';
+import path from 'node:path';
 
-import YAML from "js-yaml";
+import YAML from 'js-yaml';
 
 /**
  * Load YAML or JSON values.
  *
  * @param {string} filePath Path to YAML or JSON file.
- * @returns {object} Parsed values.
+ * @returns {Record<string, unknown>} Parsed values.
  */
 export function loadYamlOrJson(filePath) {
-  const raw = fs.readFileSync(filePath, "utf8");
+  // Check if file exists before attempting to read
+  if (!fs.existsSync(filePath)) {
+    throw new Error(
+      `Values file not found: ${filePath}\n` +
+        'Check that the file exists and the path is correct.',
+    );
+  }
+
+  const raw = fs.readFileSync(filePath, 'utf8');
 
   if (/\.ya?ml$/i.test(filePath)) {
-    return YAML.load(raw) || {};
+    return /** @type {Record<string, unknown>} */ (YAML.load(raw) || {});
   }
   if (/\.json$/i.test(filePath)) {
-    return JSON.parse(raw);
+    return /** @type {Record<string, unknown>} */ (JSON.parse(raw));
   }
 
   throw new Error(`Unsupported values file: ${filePath}`);
@@ -27,30 +35,45 @@ export function loadYamlOrJson(filePath) {
  *
  * @param {string} cwd Current working directory.
  * @param {string} [explicitFile] Explicit config file path.
- * @returns {object|null} Parsed config object or null if not found.
+ * @returns {Record<string, unknown> | null} Parsed config object or null if not found.
  */
 export function loadProjectConfig(cwd, explicitFile) {
+  if (explicitFile) {
+    const abs = path.isAbsolute(explicitFile)
+      ? explicitFile
+      : path.join(cwd, explicitFile);
+    if (!fs.existsSync(abs)) {
+      throw new Error(
+        `Config file not found: ${abs}\n` +
+          'The --config-file path was explicitly provided but does not exist.',
+      );
+    }
+  }
+
   const candidates = explicitFile
     ? [explicitFile]
     : [
-        "js-tmpl.config.yaml",
-        "js-tmpl.config.yml",
-        "js-tmpl.config.json",
-        path.join("config", "js-tmpl.yaml"),
-        path.join("config", "js-tmpl.json"),
+        'js-tmpl.config.yaml',
+        'js-tmpl.config.yml',
+        'js-tmpl.config.json',
+        path.join('config', 'js-tmpl.yaml'),
+        path.join('config', 'js-tmpl.json'),
       ];
 
   for (const rel of candidates) {
     const abs = path.isAbsolute(rel) ? rel : path.join(cwd, rel);
-    if (!fs.existsSync(abs)) {continue;}
+    if (!fs.existsSync(abs)) {
+      continue;
+    }
 
-    const raw = fs.readFileSync(abs, "utf8");
+    const raw = fs.readFileSync(abs, 'utf8');
 
-    if (/\.ya?ml$/.test(abs)) {
-      return YAML.load(raw) || {};
+    if (/\.ya?ml$/i.test(abs)) {
+      return /** @type {Record<string, unknown>} */ (YAML.load(raw) || {});
     }
-    if (/\.json$/.test(abs)) {
-      return JSON.parse(raw);
+
+    if (/\.json$/i.test(abs)) {
+      return /** @type {Record<string, unknown>} */ (JSON.parse(raw));
     }
   }
 

package/src/config/resolver.js

@@ -1,38 +1,42 @@
-import fs from "node:fs";
-import path from "node:path";
-import process from "node:process";
+import path from 'node:path';
+import process from 'node:process';
 
-import { DEFAULTS } from "./defaults.js";
-import { loadProjectConfig,loadYamlOrJson } from "./loader.js";
-import { buildView } from "./view.js";
+import { DEFAULTS } from './defaults.js';
+import { loadProjectConfig, loadYamlOrJson } from './loader.js';
+import { buildView, pickEnv } from './view.js';
 
 /**
- * Lookup default values file in valuesDir.
- * Searches for: default.yaml, default.yml
- *
- * @param {string} valuesDir - Absolute path to values directory
- * @returns {string|null} - Path to default values file or null if not found
+ * Resolve valuesFile path based on valuesDir
+ * @param {string} valuesFile - The values file name or path
+ * @param {string} valuesDir - Values directory (may be empty string)
+ * @param {string} cwd - Current working directory
+ * @returns {string} Absolute path to values file
  */
-function lookupDefaultValuesFile(valuesDir) {
-  const candidates = ["default.yaml", "default.yml"];
+function resolveValuesFilePath(valuesFile, valuesDir, cwd) {
+  // If absolute, use as-is
+  if (path.isAbsolute(valuesFile)) {
+    return valuesFile;
+  }
 
-  for (const filename of candidates) {
-    const filepath = path.join(valuesDir, filename);
-    if (fs.existsSync(filepath)) {
-      return filepath;
-    }
+  // If valuesDir is set (truthy), use it as base
+  if (valuesDir) {
+    const absoluteValuesDir = path.isAbsolute(valuesDir)
+      ? valuesDir
+      : path.join(cwd, valuesDir);
+    return path.join(absoluteValuesDir, valuesFile);
   }
 
-  return null;
+  // Otherwise, resolve from cwd
+  return path.join(cwd, valuesFile);
 }
 
 /**
  * Resolve final config using:
  * defaults < projectConfig < cliArgs
  *
- * @param {object} cli - CLI arguments
- * @param {string} cwd - Current working directory
- * @returns {object} - Resolved configuration
+ * @param {import('../types.js').CliArgs} cli - CLI arguments
+ * @param {string} [cwd] - Current working directory
+ * @returns {import('../types.js').TemplateConfig} - Resolved configuration
  */
 export function resolveConfig(cli, cwd = process.cwd()) {
   const projectConfig = loadProjectConfig(cwd, cli.configFile);
@@ -43,28 +47,41 @@ export function resolveConfig(cli, cwd = process.cwd()) {
     ...cli,
   };
 
+  /** @param {string} p */
   const abs = (p) => (path.isAbsolute(p) ? p : path.join(cwd, p));
 
-  // If valuesFile not specified, try to find default.yaml in valuesDir
-  let valuesFile = mergedConfig.valuesFile;
-  if (!valuesFile) {
-    const valuesDir = abs(mergedConfig.valuesDir);
-    valuesFile = lookupDefaultValuesFile(valuesDir);
-
-    if (!valuesFile) {
-      throw new Error(
-        `Missing valuesFile. Use --values or create ${mergedConfig.valuesDir}/default.yaml`
-      );
-    }
+  // Validate valuesFile is provided
+  if (!mergedConfig.valuesFile) {
+    throw new Error(
+      'Missing required configuration: valuesFile\n' +
+        'Provide via:\n' +
+        '  - CLI: --values path/to/values.yaml\n' +
+        '  - Config: valuesFile: "path/to/values.yaml" in js-tmpl.config.yaml',
+    );
   }
 
-  const values = loadYamlOrJson(abs(valuesFile));
+  // Resolve path - simple logic based on valuesDir presence
+  const valuesFilePath = resolveValuesFilePath(
+    mergedConfig.valuesFile,
+    mergedConfig.valuesDir,
+    cwd,
+  );
+
+  const values = loadYamlOrJson(valuesFilePath);
+
+  const hasEnvConfig = mergedConfig.envKeys?.length || mergedConfig.envPrefix;
+  const env = hasEnvConfig
+    ? pickEnv({
+        keys: mergedConfig.envKeys || [],
+        prefix: mergedConfig.envPrefix || '',
+      })
+    : {};
 
   return {
     templateDir: abs(mergedConfig.templateDir),
-    partialsDir: abs(mergedConfig.partialsDir),
+    partialsDir: mergedConfig.partialsDir ? abs(mergedConfig.partialsDir) : '',
     outDir: abs(mergedConfig.outDir),
     extname: mergedConfig.extname,
-    view: buildView(values),
+    view: buildView(values, env),
   };
 }

package/src/config/view.js

@@ -1,6 +1,53 @@
-export function buildView(values, env = process.env) {
+/**
+ * Build the view object by merging values with environment data.
+ *
+ * **Reserved key:** `env` is always set to the provided environment object.
+ * If `values` contains a top-level `env` key, a warning is logged and
+ * the key is overwritten.
+ *
+ * @param {Record<string, unknown>} values
+ * @param {Record<string, string>} [env]
+ * @returns {Record<string, unknown>}
+ */
+export function buildView(values, env = {}) {
+  if ('env' in values) {
+    console.warn(
+      'Warning: "env" is a reserved key in js-tmpl and will be overwritten.\n' +
+        'Rename the "env" key in your values file to avoid this.',
+    );
+  }
   return {
     ...values,
     env,
   };
 }
+
+/**
+ * Pick environment variables by explicit keys and/or prefix.
+ *
+ * @param {object} options
+ * @param {string[]} options.keys - Explicit key names to include.
+ * @param {string} options.prefix - Include all vars starting with this prefix.
+ * @param {Record<string, string | undefined>} [source] - Env source (default: process.env).
+ * @returns {Record<string, string>}
+ */
+export function pickEnv({ keys = [], prefix = '' }, source = process.env) {
+  /** @type {Record<string, string>} */
+  const result = {};
+
+  for (const k of keys) {
+    if (k in source) {
+      result[k] = /** @type {string} */ (source[k]);
+    }
+  }
+
+  if (prefix) {
+    for (const k of Object.keys(source)) {
+      if (k.startsWith(prefix)) {
+        result[k] = /** @type {string} */ (source[k]);
+      }
+    }
+  }
+
+  return result;
+}

package/src/engine/contentRenderer.js

@@ -1,12 +1,16 @@
-import fs from "node:fs/promises";
+import fs from 'node:fs/promises';
 
-import Handlebars from "handlebars";
+import Handlebars from 'handlebars';
 
 /**
  * Render template file with Handlebars & view object.
+ * @param {string} filePath
+ * @param {Record<string, unknown>} view
+ * @param {typeof Handlebars} [hbs] - Scoped Handlebars instance; falls back to global
+ * @returns {Promise<string>}
  */
-export async function renderContent(filePath, view) {
-  const raw = await fs.readFile(filePath, "utf8");
-  const compile = Handlebars.compile(raw);
+export async function renderContent(filePath, view, hbs) {
+  const raw = await fs.readFile(filePath, 'utf8');
+  const compile = (hbs || Handlebars).compile(raw);
   return compile(view);
 }

package/src/engine/partials.js

@@ -1,41 +1,117 @@
-import fs from "node:fs/promises";
-import path from "node:path";
+import fs from 'node:fs/promises';
+import path from 'node:path';
 
-import Handlebars from "handlebars";
+const VALID_SEGMENT = /^\w+$/;
 
 /**
- * Register partials from a directory.
- * - root partials use prefix "_"
- * - group partials under "@group"
+ * Validate a partial name segment (directory or file basename).
+ * @param {string[]} segments
+ * @param {string} filePath
  */
-export async function registerPartials(partialsDir, ext = ".hbs") {
-  const entries = await fs.readdir(partialsDir, { withFileTypes: true });
+function validateSegments(segments, filePath) {
+  if (!VALID_SEGMENT.test(segments.join(''))) {
+    throw new Error(
+      `Invalid partial name segment '${segments.join('>')}' in ${filePath} — only alphanumeric and underscore allowed`,
+    );
+  }
+}
+
+/**
+ * Derive a partial entry from a file path.
+ *
+ * @param {string} partialsDir - Root partials directory
+ * @param {string} ext - Template extension (e.g. ".hbs")
+ * @param {string} filePath - Relative path from partialsDir
+ * @param {boolean} isFlat - If true, register by filename only; otherwise namespace by path
+ * @returns {{ name: string, source: string }}
+ */
+function processPartialFile(partialsDir, ext, filePath, isFlat) {
+  const abs = path.join(partialsDir, filePath);
+
+  // Flat by filename: "name.hbs" → "name"
+  if (isFlat) {
+    const name = path.basename(filePath, ext);
+    validateSegments([name], abs);
+    return { name, source: abs };
+  }
+
+  // Namespace by path, e.g.:
+  // - "dir/name.hbs" → "dir.name"
+  // - "dir/sub/name.hbs" → "dir.sub.name"
+  // - "name.hbs" → "name" (no nesting).
+  const segments = filePath.slice(0, -ext.length).split(path.sep);
+  validateSegments(segments, abs);
+  return { name: segments.join('.'), source: abs };
+}
+
+/**
+ * Scan partialsDir recursively and collect all partial entries.
+ * @param {string} partialsDir
+ * @param {string} ext
+ * @returns {Promise<Array<{ name: string, source: string }>>}
+ */
+async function scanPartialFiles(partialsDir, ext) {
+  const allFiles = await fs.readdir(partialsDir, { recursive: true });
+
+  return allFiles
+    .filter((f) => f.endsWith(ext))
+    .map((f) => {
+      const isFlat = f.startsWith('@');
+      return processPartialFile(partialsDir, ext, f, isFlat);
+    });
+}
+
+/**
+ * Check for duplicate partial names and throw if found.
+ * @param {Array<{ name: string, source: string }>} entries
+ * @param {string} partialsDir
+ */
+function checkDuplicates(entries, partialsDir) {
+  /** @type {Map<string, string>} */
+  const seen = new Map();
 
   for (const entry of entries) {
-    const abs = path.join(partialsDir, entry.name);
-
-    if (entry.isDirectory()) {
-      // handle namespacing
-      if (entry.name.startsWith("@")) {
-        const group = entry.name.slice(1);
-        const groupFiles = await fs.readdir(abs);
-
-        for (const f of groupFiles) {
-          if (!f.endsWith(ext)) {continue;}
-          const key = path.basename(f, ext);
-          const name = `${group}.${key}`;
-          const content = await fs.readFile(path.join(abs, f), "utf8");
-          Handlebars.registerPartial(name, content);
-        }
-      }
-      continue;
+    const existing = seen.get(entry.name);
+    if (existing) {
+      const rel1 = path.relative(partialsDir, existing);
+      const rel2 = path.relative(partialsDir, entry.source);
+      throw new Error(
+        `Duplicate partial name '${entry.name}' — registered by both:\n` +
+          `  - ${rel1}\n` +
+          `  - ${rel2}\n` +
+          `Use namespaced directories to avoid collisions.`,
+      );
     }
+    seen.set(entry.name, entry.source);
+  }
+}
 
-    // root partial
-    if (entry.name.startsWith("_") && entry.name.endsWith(ext)) {
-      const content = await fs.readFile(abs, "utf8");
-      const key = entry.name.slice(1, -ext.length);
-      Handlebars.registerPartial(key, content);
-    }
+/**
+ * Register partials from a directory onto a Handlebars instance.
+ *
+ * Naming conventions:
+ *   - `name.hbs` in root → "name"
+ *   - `dir/name.hbs` → "dir.name" (namespaced by directory path)
+ *   - `@dir/` at root → flatten entire subtree (filename only)
+ *
+ * Throws on duplicate partial names or invalid name segments.
+ * Skips silently if partialsDir is falsy. Throws if the directory does not exist.
+ *
+ * @param {string} partialsDir - Path to partials directory
+ * @param {string} ext - Template file extension (e.g. ".hbs")
+ * @param {import('handlebars')} hbs - Handlebars instance to register partials on
+ */
+export async function registerPartials(partialsDir, ext, hbs) {
+  if (!partialsDir) {
+    return;
+  }
+
+  const allPartials = await scanPartialFiles(partialsDir, ext);
+
+  checkDuplicates(allPartials, partialsDir);
+
+  for (const p of allPartials) {
+    const content = await fs.readFile(p.source, 'utf8');
+    hbs.registerPartial(p.name, content);
   }
 }

package/src/engine/pathRenderer.js

@@ -1,9 +1,12 @@
-import path from "node:path";
+import path from 'node:path';
 
-import { getNested } from "../utils/object.js";
+import { getNested } from '../utils/object.js';
 
 /**
  * Render `${var}` placeholders in each segment of the relPath.
+ * @param {string} relPath
+ * @param {Record<string, unknown>} view
+ * @returns {string}
  */
 export function renderPath(relPath, view) {
   const segments = relPath.split(path.sep);
@@ -12,8 +15,8 @@ export function renderPath(relPath, view) {
     //NOSONAR -- ignore S5842: Regular expression is safe here
     seg.replace(/\$\{([^}]+)\}/g, (_, expr) => {
       const v = getNested(view, expr.trim());
-      return String(v ?? "");
-    })
+      return String(v ?? '');
+    }),
   );
 
   return path.join(...rendered);

package/src/engine/renderDirectory.js

@@ -1,18 +1,24 @@
-import path from "node:path";
+import path from 'node:path';
 
-import { ensureDir, writeFileSafe } from "../utils/fs.js";
-import { renderContent } from "./contentRenderer.js";
-import { registerPartials } from "./partials.js";
-import { renderPath } from "./pathRenderer.js";
-import { walkTemplateTree } from "./treeWalker.js";
+import Handlebars from 'handlebars';
+
+import { ensureDir, writeFileSafe } from '../utils/fs.js';
+import { renderContent } from './contentRenderer.js';
+import { registerPartials } from './partials.js';
+import { renderPath } from './pathRenderer.js';
+import { walkTemplateTree } from './treeWalker.js';
 
 /**
  * Main rendering orchestrator.
+ * @param {import('../types.js').TemplateConfig} cfg
+ * @param {typeof import('handlebars')} [hbs] - Optional Handlebars instance (creates an isolated one if omitted)
+ * @returns {Promise<void>}
  */
-export async function renderDirectory(cfg) {
+export async function renderDirectory(cfg, hbs) {
   const { templateDir, partialsDir, outDir, view, extname } = cfg;
 
-  await registerPartials(partialsDir, extname);
+  hbs = hbs || Handlebars.create();
+  await registerPartials(partialsDir, extname, hbs);
 
   const files = await walkTemplateTree(templateDir, extname);
 
@@ -20,10 +26,10 @@ export async function renderDirectory(cfg) {
     const relRendered = renderPath(file.relPath, view);
     const target = path.join(
       outDir,
-      relRendered.replace(new RegExp(`${extname}$`), "")
+      relRendered.replace(new RegExp(`${extname}$`), ''),
     );
 
-    const content = await renderContent(file.absPath, view);
+    const content = await renderContent(file.absPath, view, hbs);
 
     await ensureDir(path.dirname(target));
     await writeFileSafe(target, content);

package/src/engine/treeWalker.js

@@ -1,22 +1,28 @@
-import fs from "node:fs/promises";
-import path from "node:path";
+import fs from 'node:fs/promises';
+import path from 'node:path';
 
 /**
  * BFS async folder walker.
+ * @param {string} rootDir
+ * @param {string} [ext]
+ * @param {Array<string | RegExp>} [ignore]
+ * @returns {Promise<import('../types.js').TemplateFile[]>}
  */
-export async function walkTemplateTree(rootDir, ext = ".hbs", ignore = []) {
+export async function walkTemplateTree(rootDir, ext = '.hbs', ignore = []) {
   const results = [];
-  const queue = [""];
+  const queue = [''];
 
   while (queue.length) {
-    const rel = queue.shift();
+    const rel = /** @type {string} */ (queue.shift());
     const abs = path.join(rootDir, rel);
     const stat = await fs.stat(abs);
 
     if (stat.isDirectory()) {
-      const items = await fs.readdir(abs);
+      const items = (await fs.readdir(abs)).sort();
       for (const name of items) {
-        if (ignore.some((i) => matchIgnore(name, i))) {continue;}
+        if (ignore.some((i) => matchIgnore(name, i))) {
+          continue;
+        }
         queue.push(rel ? path.join(rel, name) : name);
       }
     } else if (path.extname(abs) === ext) {
@@ -27,6 +33,11 @@ export async function walkTemplateTree(rootDir, ext = ".hbs", ignore = []) {
   return results;
 }
 
+/**
+ * @param {string} name
+ * @param {string | RegExp} rule
+ * @returns {boolean}
+ */
 function matchIgnore(name, rule) {
   return rule instanceof RegExp ? rule.test(name) : rule === name;
 }

package/src/index.js

@@ -1,2 +1,2 @@
-export * from "./config/resolver.js";
-export * from "./engine/renderDirectory.js";
+export * from './config/resolver.js';
+export * from './engine/renderDirectory.js';

package/src/types.js

@@ -0,0 +1,30 @@
+/**
+ * @typedef {object} CliArgs
+ * @property {string} [command]
+ * @property {string} [templateDir]
+ * @property {string} [valuesFile]
+ * @property {string} [outDir]
+ * @property {string} [partialsDir]
+ * @property {string} [configFile]
+ * @property {string} [extname]
+ * @property {string} [valuesDir]
+ * @property {string[]} [envKeys]
+ * @property {string} [envPrefix]
+ */
+
+/**
+ * @typedef {object} TemplateConfig
+ * @property {string} templateDir
+ * @property {string} partialsDir
+ * @property {string} outDir
+ * @property {string} extname
+ * @property {Record<string, unknown>} view
+ */
+
+/**
+ * @typedef {object} TemplateFile
+ * @property {string} absPath
+ * @property {string} relPath
+ */
+
+export {}; //NOSONAR

package/src/utils/fs.js

@@ -1,5 +1,5 @@
-import fs from "node:fs/promises";
-import path from "node:path";
+import fs from 'node:fs/promises';
+import path from 'node:path';
 
 /** Safe mkdir -p
  * @param {string} dir Directory path to create
@@ -13,7 +13,7 @@ export async function ensureDir(dir) {
  * @param {string} content Content to write
  */
 export async function writeFileSafe(file, content) {
-  await fs.writeFile(file, content, "utf8");
+  await fs.writeFile(file, content, 'utf8');
 }
 
 /** Resolve path relative to cwd
@@ -35,7 +35,8 @@ export function resolvePath(p, cwd = process.cwd()) {
  * @returns {string} Absolute path.
  */
 export function safeResolvePath(...segments) {
-  const isAbsolute = segments ? segments[0] && path.isAbsolute(segments[0]) : false;
+  const isAbsolute =
+    segments.length > 0 && segments[0] && path.isAbsolute(segments[0]);
   if (isAbsolute) {
     return path.resolve(...segments);
   }

package/src/utils/object.js

@@ -1,10 +1,15 @@
 /**
  * Retrieve nested value: getNested(obj, "a.b.c")
+ * @param {Record<string, unknown>} obj
+ * @param {string} key
+ * @returns {unknown}
  */
 export function getNested(obj, key) {
-  console.log("getNested", obj, key);
-  
   return key
-    .split(".")
-    .reduce((acc, k) => (acc?.[k] ?? undefined), obj);
+    .split('.')
+    .reduce(
+      (/** @type {unknown} */ acc, /** @type {string} */ k) =>
+        /** @type {Record<string, unknown>} */ (acc)?.[k] ?? undefined,
+      obj,
+    );
 }