@baravak/risloo-profile-cli 4.46.3 → 4.75.0

package/CLAUDE.md

@@ -1,188 +1,5 @@
 # CLAUDE.md
 
-## Project Overview
+Pointer only — all project instructions live in [AGENTS.md](AGENTS.md). Edit that file, not this one.
 
-**@baravak/risloo-profile-cli** is a Node.js CLI tool that converts psychological test result JSON data into SVG and PNG profile/report images. It supports 81+ psychological questionnaires with Persian/Farsi labeling.
-
-Published as npm package: `@baravak/risloo-profile-cli` (v4.46.2, MIT)
-
----
-
-## Directory Structure
-
-```
-risloo-extractor-app/
-├── bin/
-│   └── risloo.js                # CLI entry point
-├── src/
-│   ├── cli.js                   # Commander.js command definitions
-│   ├── cli-commands/
-│   │   ├── Executor.js          # Base executor class
-│   │   ├── ExtractExecutor.js   # Profile/report/sheet extraction logic
-│   │   ├── GiftExecutor.js      # Gift card generation
-│   │   └── utilities/           # BaseOps, Benchmarker, Response, Errors, Status codes
-│   ├── Profile.js               # Base Profile class (math utilities)
-│   ├── Gift.js                  # Gift card class
-│   ├── samples/                 # JS controller files — one per profile (e.g. BSCT93.js)
-│   ├── handlebars/
-│   │   ├── init.js              # Handlebars initialization
-│   │   ├── helpers.js           # Entry point for all helpers
-│   │   ├── helpers/             # 45+ geometry helper modules
-│   │   ├── importPartials.js    # Partials loader
-│   │   └── polygon.js           # Polygon drawing logic
-│   ├── helpers/                 # Math helpers (angleABS, polarXY, gauge, polygonXY)
-│   ├── qrcode/                  # QR code generation & rendering
-│   └── publish/
-│       ├── json/profiles/       # Template JSON per sample (e.g. BSCT93.json)
-│       ├── json/gift/           # Gift template data
-│       ├── test.js              # Auto-test all samples
-│       └── bot.js               # Post-publish automation
-├── views/
-│   ├── profiles/samples/        # Handlebars SVG templates (.hbs)
-│   └── gift.hbs
-└── package.json
-```
-
----
-
-## Commands
-
-```bash
-# Test a single profile (generates SVG in ./temp)
-./bin/risloo.js E <NAME> -d ./src/publish/json/profiles/<NAME>.json -a ./temp
-
-# Watch mode
-risloo extract <NAME> profile -i local -d ./src/publish/json/profiles/<NAME>.json -o local -a ./temp -w
-
-# Generate gift card
-risloo gift -i raw-json -d '{"code":"..."}' -o local -a ./output
-
-# Test all samples
-npm test   # → node ./src/publish/test.js
-```
-
----
-
-## Profile Development Workflow (Figma → Code)
-
-### Design Source
-
-Each profile is designed in Figma. Per task, one or both of the following may be provided:
-
-- **Figma design file** — connect via Figma MCP to read layer dimensions and structure. The relevant layer is named **Chart**.
-- **Figma handoff file** — contains additional implementation notes and specs. May state that this profile is similar to an existing one (e.g. "similar to BSCT93 with these changes"). In that case: find the referenced profile's JS + HBS files, use them as the base, and apply only the described differences.
-
-> **Important:** The Figma MCP reads text layers only — it does NOT read Figma comments. Designers often leave critical specs (thresholds, coefficients, pixel values) as Figma comments. Always ask the user to share designer comments before finalizing the plan.
-
-### What the HBS Draws
-
-The HBS file draws **only the Chart layer**. The library automatically injects the header (test name, dates, client info) and sidebar (logo, room info, prerequisites) via the `{{#> layout}}` wrapper. Never include these in the HBS.
-
-### SVG Coordinate System
-
-Since this is SVG, coordinate origin matters for correctness across **all** inputs:
-
-- **x=0** = left edge, increases rightward
-- **y=0** = top edge, increases downward
-- Horizontal bars fill left → right: `{{bar (BAR_WIDTH * factor.p) height ...}}`
-- Vertical total bar fills bottom → up via the transform trick: `translate(0, barHeight - barHeight * p)`
-- All positions must remain stable for edge-case inputs: 0% score, 100% score, missing data
-
-### Inside/Outside Bar Text
-
-When rendering percentage text on a bar, check if the bar is wide enough to contain the text. The threshold is specified by the designer per profile (in Figma comments):
-
-```hbs
-{{#if (boolean factor.percentage '<=' THRESHOLD)}}
-  <text x="{{math (math BAR_WIDTH '*' factor.p) '+' 6}}" ...>{{factor.percentage}} ٪</text>
-{{else}}
-  <text x="{{math (math BAR_WIDTH '*' factor.p) '-' 4}}" ...>{{factor.percentage}} ٪</text>
-{{/if}}
-```
-
-### File Structure per Profile
-
-Each profile (نیم‌رخ) consists of three files:
-
-| File | Path | Role |
-|---|---|---|
-| JSON template | `src/publish/json/profiles/<NAME>.json` | Test data / input template |
-| JS controller | `src/samples/<NAME>.js` | Data processing, geometry config |
-| HBS template | `views/profiles/samples/<NAME>.hbs` | SVG rendering |
-
-If a profile has **multiple pages**, the HBS files are named with suffixes:
-- `<NAME>_1.hbs`, `<NAME>_2.hbs`, `<NAME>_3.hbs`, ...
-
-### Dimensions & Padding Convention
-
-The chart drawing must fit within the **Main** layer in Figma.
-
-- Read the **Main** layer dimensions from Figma
-- `profile.padding` = 20 units per side
-- The `x` and `y` values (drawing area) = Main dimensions minus one padding unit each:
-  - e.g. Main = 104×255 → `{ x: 84, y: 235 }`
-
-The `dimensions` property in the JS controller adds padding back on both sides of the **Chart** layer dimensions:
-
-```js
-get dimensions() {
-  return {
-    width: 736 + 2 * this.padding.x,   // Chart layer width from Figma
-    height: 254 + 2 * this.padding.y,  // Chart layer height from Figma
-  };
-},
-```
-
-### Data / Labels Convention
-
-All data needed for rendering goes in the `labels` property of the JS controller.
-
-The data structure is typically derived from a Python script that outputs a JSON file — flattened with `_` separators — which maps source fields to their `labels` keys.
-
-```js
-get labels() {
-  return {
-    // flat_key: value
-    score_total: ...,
-    subscale_anxiety: ...,
-  };
-}
-```
-
----
-
-## Tech Stack
-
-| Area | Technology |
-|---|---|
-| Language | JavaScript (Node.js, no build step) |
-| CLI | Commander.js |
-| Templating | Handlebars (SVG generation) |
-| Image output | Sharp (SVG → PNG) |
-| Dates | Moment.js + moment-jalaali (Persian calendar) |
-| QR codes | qrcode |
-| File watching | Chokidar |
-| Package manager | Yarn |
-| Design source | Figma (via MCP) |
-
----
-
-## Naming Conventions
-
-- `items` — array of data elements to draw
-- `raw` — total/aggregate element
-- `ticks` — graduation marks on profiles
-- `s` suffix — denotes arrays (not `Arr`)
-- Sample names: uppercase acronym + year (e.g. `BSCT93`, `BEQI93`, `16PF93`)
-- Dataset score structure: `dataset.score = [{ label: { eng, ... }, mark }]`
-
----
-
-## Publishing
-
-```bash
-npm version <patch|minor|major>
-npm publish
-# prepublishOnly: npm test
-# postpublish: npm run bot
-```
+@AGENTS.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baravak/risloo-profile-cli",
-  "version": "4.46.3",
+  "version": "4.75.0",
   "description": "**Risloo Profile CLI** is a library for creating profiles, reports and sheets for *psychological* samples.",
   "main": "bin/risloo.js",
   "publishConfig": {

package/src/cli-commands/Executor.js

@@ -1,5 +1,5 @@
 const { checkAndLoad, loadStdin, ensureDirExistence, createSVG, createPNG } = require("./utilities/BaseOps");
-const Handlebars = require("../handlebars/init");
+const createHandlebars = require("../handlebars/init");
 const path = require("path");
 const Benchmarker = require("./utilities/Benchmarker");
 const Response = require("./utilities/Response");
@@ -74,8 +74,14 @@ class Executor {
     }
   }
 
+  _addHandlebarsPromise(partials = {}) {
+    this.promises["handlebars"] = Promise.resolve(partials).then(createHandlebars);
+    return this.promises["handlebars"];
+  }
+
   async _renderTemplate(ctx, templateBuffer) {
-    const template = (await Handlebars).compile(templateBuffer.toString(), "utf-8");
+    const hbs = await this.promises.handlebars;
+    const template = hbs.compile(templateBuffer.toString(), "utf-8");
     return template(ctx);
   }
 

package/src/cli-commands/ExtractExecutor.js

@@ -7,7 +7,8 @@ const { FileNotFoundError } = require("./utilities/CustomErrors");
 
 class ExtractExecutor extends Executor {
   samplesJSDir = path.join(__dirname, "..", "samples");
-  profilesTemplatesDir = path.join(__dirname, "..", "..", "views", "profiles", "samples");
+  profilesDir = path.join(__dirname, "..", "..", "views", "profiles");
+  profilesTemplatesDir = path.join(this.profilesDir, "samples");
 
   constructor(options) {
     super(options);
@@ -39,6 +40,18 @@ class ExtractExecutor extends Executor {
     });
   }
 
+  _addProfileHandlebarsPromise() {
+    const { promises, response } = this;
+    const partials = promises["js"].then((Profile) => Profile.partials || {});
+    const handlebarsPromise = this._addHandlebarsPromise(partials);
+
+    promises["handlebars"] = handlebarsPromise.catch((err) =>
+      response.setStatus(EXTRACT_STATUS["TEMPLATE_NOT_FOUND"], err)
+    );
+
+    return promises["handlebars"];
+  }
+
   _addProfilesTemplatePromises() {
     const { sample, dirs, profilesTemplatesDir, promises, response } = this;
 
@@ -77,6 +90,7 @@ class ExtractExecutor extends Executor {
         name: options.name,
       };
 
+      this._addProfileHandlebarsPromise();
       this._addProfilesTemplatePromises();
     }
 
@@ -124,7 +138,7 @@ class ExtractExecutor extends Executor {
   }
 
   _watch() {
-    const { command, dirs, input, response, benchmarker, promises } = this;
+    const { dirs, input, promises } = this;
 
     const opts = {
       awaitWriteFinish: {
@@ -137,38 +151,58 @@ class ExtractExecutor extends Executor {
       dirs.templates.map((templateFileDir, index) => {
         chokidar.watch(templateFileDir, opts).on("change", () => {
           promises["templates"][index] = checkAndLoad(templateFileDir);
-          benchmarker?.restart(command);
-          this._createProfile("with-sidebar", ["svg"]).then(() => {
-            benchmarker?.end();
-            response.setTime(benchmarker?.totalTime);
-            response.showOutput();
-          });
+          this._renderWatchedProfile();
         });
       });
     });
 
+    this._resetPartialWatcher(opts).catch(() => {});
+
     chokidar.watch(dirs.sampleJS, opts).on("change", () => {
       promises["js"] = checkAndImport(dirs.sampleJS);
-      benchmarker?.restart(command);
-      this._createProfile("with-sidebar", ["svg"]).then(() => {
-        benchmarker?.end();
-        response.setTime(benchmarker?.totalTime);
-        response.showOutput();
-      });
+      this._addProfileHandlebarsPromise();
+      this._resetPartialWatcher(opts).catch(() => {});
+      this._renderWatchedProfile();
     });
     
     if(input.type === 'local') chokidar.watch(input.data, opts).on('change', () => {
       promises["input"] = checkAndLoad(input.data).then((json) => Promise.resolve(JSON.parse(json)));
-      benchmarker?.restart(command);
-      this._createProfile("with-sidebar", ["svg"]).then(() => {
-        benchmarker?.end();
-        response.setTime(benchmarker?.totalTime);
-        response.showOutput();
-      });
-
+      this._renderWatchedProfile();
     })
   }
 
+  async _resetPartialWatcher(opts) {
+    const { dirs, profilesDir, promises } = this;
+    const Profile = await promises["js"];
+    const partialDirs = Object.values(Profile.partials || {}).map((partialFile) =>
+      path.join(profilesDir, partialFile)
+    );
+
+    dirs["partials"] = partialDirs;
+
+    if (this.partialWatcher) await this.partialWatcher.close();
+    if (!partialDirs.length) {
+      this.partialWatcher = null;
+      return;
+    }
+
+    this.partialWatcher = chokidar.watch(partialDirs, opts).on("change", () => {
+      this._addProfileHandlebarsPromise();
+      this._renderWatchedProfile();
+    });
+  }
+
+  _renderWatchedProfile() {
+    const { command, response, benchmarker } = this;
+
+    benchmarker?.restart(command);
+    return this._createProfile("with-sidebar", ["svg"]).then(() => {
+      benchmarker?.end();
+      response.setTime(benchmarker?.totalTime);
+      response.showOutput();
+    });
+  }
+
   _createProfileOutputName(variant) {
     const {
       settings: {

package/src/cli-commands/GiftExecutor.js

@@ -11,6 +11,7 @@ class GiftExecutor extends Executor {
   constructor(options) {
     super(options);
 
+    this._addHandlebarsPromise();
     this._addTemplatePromise();
     this._addAvatarPromise();
 

package/src/handlebars/importPartials.js

@@ -1,51 +1,17 @@
-const fs = require("fs");
-const { readdir } = require("fs/promises");
+const fs = require("fs/promises");
 const path = require("path");
 
-// These are the profiles that might be used completely in other profiles
-const baseProfiles = [
-  "AMS93",
-  "MMFAD93",
-  "PIES93",
-  "JPFQ93_partial",
-  "JPFQ93_partial2",
-  "FACES93_1_partial",
-  "FACES93_2_1_partial",
-  "FACES93_2_2_partial",
-  "EPQ93",
-  'YPI93_factors'
-];
+const partialsDir = path.join(__dirname, "..", "..", "views", "profiles");
 
-async function importPartials(hbs) {
-  const partialsDir = path.join(__dirname, "..", "..", "views", "profiles");
+async function importPartials(hbs, partials) {
+  await Promise.all(
+    Object.entries(partials).map(async ([name, relativePath]) => {
+      const template = await fs.readFile(path.join(partialsDir, relativePath), "utf-8");
+      hbs.registerPartial(name, template);
+    })
+  );
 
-  let baseProfilePromises = baseProfiles.map((profileName) => {
-    new Promise(function (resolve, reject) {
-      fs.readFile(path.join(partialsDir, "samples", `${profileName}.hbs`), "utf-8", (err, template) => {
-        if (err) reject(err);
-        hbs.registerPartial(profileName, template);
-        resolve(true);
-      });
-    });
-  });
-
-  return readdir(partialsDir).then((partialFiles) => {
-    let generalPartialsPromises = partialFiles.map(
-      (partialFile) =>
-        new Promise(function (resolve, reject) {
-          const matches = /^([^.]+).(hbs|css|js)$/.exec(partialFile);
-          if (!matches) return resolve(true);
-          const name = matches[1];
-          fs.readFile(path.join(partialsDir, partialFile), "utf-8", (err, template) => {
-            if (err) reject(err);
-            hbs.registerPartial(name, template);
-            resolve(true);
-          });
-        })
-    );
-
-    return Promise.all(generalPartialsPromises, baseProfilePromises);
-  });
+  return hbs;
 }
 
 module.exports = importPartials;

package/src/handlebars/init.js

@@ -2,14 +2,20 @@ const Handlebars = require("handlebars");
 const helpers = require("./helpers");
 const importPartials = require("./importPartials");
 
-// Add Custom Helpers to Handlebars
-for (let helper in helpers) Handlebars.registerHelper(helper, helpers[helper]);
-
-module.exports = new Promise(function (resolve, reject) {
-  // Add Partials to Handlebars
-  importPartials(Handlebars)
-    .then(() => resolve(Handlebars))
-    .catch((err) => {
-      reject(err);
-    });
-});
+const sharedPartials = {
+  fonts: "fonts.css",
+  layout: "layout.hbs",
+  sidebar: "sidebar.hbs",
+};
+
+async function createHandlebars(partials = {}) {
+  const hbs = Handlebars.create();
+
+  for (const [name, helper] of Object.entries(helpers)) {
+    hbs.registerHelper(name, helper);
+  }
+
+  return importPartials(hbs, { ...partials, ...sharedPartials });
+}
+
+module.exports = createHandlebars;