@nci-gis/js-tmpl 0.0.1-beta.2 → 0.1.0

package/README.md

@@ -1,6 +1,7 @@
 # js-tmpl
 
 > 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)
@@ -44,6 +45,7 @@ Most templating tools fail in one of two ways:
 js-tmpl sits intentionally in between.
 
 See [Motivation](docs/Motivation.md) - The full story.
+
 See [Design Principles](docs/PRINCIPLES.md) - Core philosophy guiding all decisions.
 
 ## Features
@@ -76,10 +78,11 @@ js-tmpl will search for a project config file in **exactly these locations**, in
 
 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 or defaults to `templates.partials/`
+- ✅ **Values file** — Optional via `--values` flag or `valuesFile` config (VP-8)
+- ✅ **Values directory** — Optional via `--values-dir` flag or `valuesDir` config (VP-6)
+- ✅ **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
 
@@ -137,14 +140,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
@@ -163,7 +161,7 @@ import { resolveConfig, renderDirectory } from '@nci-gis/js-tmpl';
 const config = resolveConfig({
   valuesFile: './values.yaml',
   templateDir: './templates',
-  outDir: './dist'
+  outDir: './dist',
 });
 
 await renderDirectory(config);
@@ -190,14 +188,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:
 
@@ -218,23 +213,44 @@ templates/
 → dist/production/config-my-app.yaml
 ```
 
+Use `$if{var}` / `$ifn{var}` as whole directory segments to conditionally
+include or skip files based on view data:
+
+```text
+templates/
+├── common.yaml.hbs
+├── $if{prod}/
+│   └── alerts.yaml.hbs          → written only when view.prod is truthy
+└── $ifn{prod}/
+    └── debug-panel.yaml.hbs     → written only when view.prod is falsy
+```
+
+Guards are directory-only, whole-segment, and throw loudly on missing
+variables. See [API docs](docs/API.md#path-guards--conditional-files) for
+the full semantics and rejected variants.
+
 ### 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
@@ -243,7 +259,7 @@ templates.partials/
 Think of js-tmpl as a function:
 
 ```text
-(input templates, data, config) → output files
+f(config, values/view, input templates) → files (output)
 ```
 
 There is no hidden state, no lifecycle, and no side effects.
@@ -257,14 +273,22 @@ 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` / `.yml` / `.json`) | Optional        |
+| `--values-dir DIR`       | Value-partials root (namespaced by path) | Optional        |
+| `-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            |
+
+Both `--values` and `--values-dir` are optional (VP-8, VP-6). If neither is
+supplied, `view` is `{ env: {...} }` only. Missing `{{var}}` in a template
+throws with the template's relative path and variable name (VP-9, strict
+mode).
 
 ### Examples of Usage
 
@@ -278,111 +302,35 @@ 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
 
-See [examples/yaml-templates/](examples/yaml-templates/) for a complete working example demonstrating:
-
-- Dynamic file paths with `${env.NODE_ENV}`
-- Handlebars features (loops, conditionals)
-- Root and namespaced partials
-- Multi-format output (YAML, Markdown)
+- [examples/yaml-templates/](examples/yaml-templates/) — complete walkthrough:
+  dynamic paths with `${env.NODE_ENV}`, Handlebars features (loops,
+  conditionals), root and namespaced partials, multi-format output.
+- [examples/path-guards/](examples/path-guards/) — conditional files via
+  `$if{var}` / `$ifn{var}` whole-segment path guards.
+- [examples/value-partials/](examples/value-partials/) — composing `view`
+  from multiple structured files via `--values-dir` (directory-as-namespace,
+  no merge, `@`-flatten escape).
 
 ## 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
 
@@ -414,7 +362,7 @@ For security concerns, see [SECURITY.md](SECURITY.md).
 
 ## License
 
-MIT © pasxd245
+See [LICENSE](LICENSE).
 
 ## Learn More
 
@@ -431,3 +379,7 @@ MIT © pasxd245
 - [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
+
+## Transparency
+
+AI-assisted development (e.g., Claude Code, Copilot) was used for scaffolding and iteration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nci-gis/js-tmpl",
-  "version": "0.0.1-beta.2",
+  "version": "0.1.0",
   "description": "The pure JavaScript templating engine that uses handlebars.",
   "type": "module",
   "bin": {
@@ -12,16 +12,26 @@
     }
   },
   "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": "pnpm format:code && pnpm format:md",
+    "format:check": "pnpm format:code:check && pnpm format:md:check",
+    "format:code": "prettier --write src/ tests/",
+    "format:code:check": "prettier --check src/ tests/",
+    "format:md": "prettier --write \"*.md\" \"docs/**/*.md\" \"tests/**/*.md\" \"examples/**/*.md\"",
+    "format:md:check": "prettier --check \"*.md\" \"docs/**/*.md\" \"tests/**/*.md\" \"examples/**/*.md\"",
     "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"
+    "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",
@@ -56,8 +66,31 @@
     "js-yaml": "^4.1.1"
   },
   "devDependencies": {
+    "@commitlint/cli": "^20.5.0",
+    "@commitlint/config-conventional": "^20.5.0",
     "@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"
+  },
+  "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,70 @@
 /**
  * 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 '--values-dir':
+        opts.valuesDir = args[++i];
+        break;
+
+      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,17 @@
+/** 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 / .yml / .json) — optional
+      --values-dir <dir>     Value-partials root, namespaced into view by path
+  -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: "",
-  valuesFile: "",
-  outDir: "dist",
-  extname: ".hbs",
+  templateDir: 'templates',
+  partialsDir: '',
+  valuesDir: '',
+  valuesFile: '',
+  outDir: 'dist',
+  extname: '.hbs',
+  envKeys: [],
+  envPrefix: '',
 };

package/src/config/loader.js

@@ -1,30 +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) {
   // 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."
+        'Check that the file exists and the path is correct.',
     );
   }
 
-  const raw = fs.readFileSync(filePath, "utf8");
+  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}`);
@@ -35,31 +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$/i.test(abs)) {
-      return YAML.load(raw) || {};
+      return /** @type {Record<string, unknown>} */ (YAML.load(raw) || {});
     }
 
     if (/\.json$/i.test(abs)) {
-      return JSON.parse(raw);
+      return /** @type {Record<string, unknown>} */ (JSON.parse(raw));
     }
   }