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

package/README.md

@@ -1,13 +1,14 @@
 # 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 +19,32 @@ 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:
 
-- ✅ **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
+- they are too simple to scale beyond string replacement
+- or too opinionated to embed safely in larger systems
 
-See [docs/00-Motivation.md](docs/00-Motivation.md) for the full story.
+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
 
@@ -40,6 +56,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 or defaults to `templates.partials/`
+
+### 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
@@ -173,6 +235,20 @@ templates.partials/
     └── metadata.hbs  → {{> common.metadata}}
 ```
 
+## 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
@@ -340,9 +416,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-beta.2",
   "description": "The pure JavaScript templating engine that uses handlebars.",
   "type": "module",
   "bin": {
@@ -11,6 +11,18 @@
       "import": "./src/index.js"
     }
   },
+  "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"
+  },
   "keywords": [
     "js",
     "templating",
@@ -37,6 +49,7 @@
     "node": ">=20.0.0",
     "pnpm": ">=10.0.0"
   },
+  "packageManager": "pnpm@10.22.0",
   "dependencies": {
     "config": "^4.1.1",
     "handlebars": "^4.7.8",
@@ -46,17 +59,5 @@
     "@eslint/js": "^9.39.2",
     "eslint": "^9.39.2",
     "eslint-plugin-simple-import-sort": "^12.1.1"
-  },
-  "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"
   }
-}
+}

package/src/config/defaults.js

@@ -1,7 +1,7 @@
 export const DEFAULTS = {
   templateDir: "templates",
   partialsDir: "templates.partials",
-  valuesDir: "templates.values",
+  valuesDir: "",
   valuesFile: "",
   outDir: "dist",
   extname: ".hbs",

package/src/config/loader.js

@@ -10,6 +10,14 @@ import YAML from "js-yaml";
  * @returns {object} 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."
+    );
+  }
+
   const raw = fs.readFileSync(filePath, "utf8");
 
   if (/\.ya?ml$/i.test(filePath)) {
@@ -46,10 +54,11 @@ export function loadProjectConfig(cwd, explicitFile) {
 
     const raw = fs.readFileSync(abs, "utf8");
 
-    if (/\.ya?ml$/.test(abs)) {
+    if (/\.ya?ml$/i.test(abs)) {
       return YAML.load(raw) || {};
     }
-    if (/\.json$/.test(abs)) {
+
+    if (/\.json$/i.test(abs)) {
       return JSON.parse(raw);
     }
   }

package/src/config/resolver.js

@@ -1,4 +1,3 @@
-import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 
@@ -7,23 +6,28 @@ import { loadProjectConfig,loadYamlOrJson } from "./loader.js";
 import { buildView } 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);
 }
 
 /**
@@ -45,20 +49,24 @@ export function resolveConfig(cli, cwd = process.cwd()) {
 
   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);
 
   return {
     templateDir: abs(mergedConfig.templateDir),