@baravak/risloo-profile-cli 4.46.1 → 4.46.3

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__figma__get_figma_data",
+      "Bash(mkdir -p temp)",
+      "Bash(node ./bin/risloo.js E BSCT93 -d ./src/publish/json/profiles/BSCT93.json -a ./temp)"
+    ]
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,188 @@
+# CLAUDE.md
+
+## Project Overview
+
+**@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
+```