forma-dsl-cli 0.3.9 → 0.4.0

package/README.md

@@ -36,12 +36,74 @@ tree - is refused with exit code 2.
 | `-m, --model <name>` | which model to build. Defaults to the first declared |
 | `--part <name>` | one part by name. Defaults to the only part, or every part unioned |
 | `-p, --param <name=val>` | a value for one declared param. Repeatable |
+| `--params <file>` | a JSON object of values by name. `-p` wins over it |
 | `--segments <n>` | a fixed segment count for every curve |
 | `--min-angle <deg>` | smallest angle between adjacent segments of a curve |
 | `--min-edge <n>` | smallest length a curve segment may be shortened to |
 | `--max-nodes <n>` | refuse a document that would build more blocks than this |
 | `-q, --quiet` | do not print the summary |
 
+## Passing parameters
+
+Three ways, and they compose.
+
+**One at a time, on the command line.** A value is JSON where it parses as JSON, and the
+string as written otherwise - so there is no second layer of quoting to get wrong:
+
+```bash
+forma render part.forma -p count=6 -p center=true -p size=[10,20] -p label=M6
+```
+
+| Written | Arrives as |
+| --- | --- |
+| `-p count=6` | the number `6` |
+| `-p center=true` | the boolean `true` |
+| `-p size=[10,20]` | the list `[10, 20]` |
+| `-p label=M6` | the string `"M6"` |
+
+**From a file.** `--params` takes a JSON object of values by name - the thing you commit and
+diff, rather than assemble in a shell loop:
+
+```json
+{
+  "height": 36,
+  "label": "M6",
+  "center": true
+}
+```
+
+```bash
+forma render riser.forma --params params.json -o riser.stl
+```
+
+It has to be a JSON **object**. An array or a bare number parses but names nothing, and is
+refused with exit code 2 rather than quietly contributing nothing. Like every other path, it
+must resolve inside the directory the command runs in.
+
+**Both.** `-p` wins over `--params`, which is what a build matrix wants: the values every
+variant shares live in the file, and the one that varies goes on the line.
+
+```bash
+for h in 8 20 40; do
+  forma render riser.forma --params shared.json -p "height=$h" -o "build/riser-$h.stl"
+done
+```
+
+And the document will tell you what it takes, so the first `params.json` need not be written
+by hand:
+
+```bash
+forma params riser.forma --json | jq 'map({(.name): .default}) | add' > params.json
+```
+
+```json
+{
+  "height": 20,
+  "label": "A",
+  "center": false
+}
+```
+
 ## In a pipeline
 
 Only what was asked for goes to stdout — the STL under `-o -`, and the listings. The summary
@@ -57,13 +119,13 @@ that does not build, and `2` for a mistake in the invocation itself.
 A failure is reported where an editor and a CI annotation can both find it:
 
 ```
-riser.forma:7:23: size must be positive
- 5 |   part "body" {
- 6 |     extrude {
- 7 |       rect { size = [-40, 20] }
-   |                     ^
- 8 |     }
- 9 |   }
+riser.forma:7:7: rounded_rect: unknown attribute "corner_radius" - rounded_rect reads "center", "radius", "segments", "size"
+5 |     extrude {
+6 |       height = var.height
+7 |       rounded_rect { size = [40, 20]  corner_radius = 4 }
+  |       ^
+8 |     }
+9 |   }
 ```
 
 Build a matrix of variants from what the document itself declares:
@@ -91,8 +153,11 @@ millimetres.
 | [`forma-dsl`](https://www.npmjs.com/package/forma-dsl) | the language, its evaluator and the geometry kernel binding |
 | [`forma-dsl-mcp`](https://www.npmjs.com/package/forma-dsl-mcp) | an MCP server: it knows the language, solves what it writes, and produces `.forma` files |
 
-The [reference manual](https://kalpak44.github.io/forma-dsl/docs/) documents the language, and
-the [editor](https://kalpak44.github.io/forma-dsl/editor/) runs the same kernel in a browser.
+**[The site](https://kalpak44.github.io/forma-dsl/)** ·
+**[Try the editor](https://kalpak44.github.io/forma-dsl/editor/)** ·
+**[Read the reference](https://kalpak44.github.io/forma-dsl/docs/)**
+
+The reference manual documents the language, and the editor runs the same kernel in a browser.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forma-dsl-cli",
-  "version": "0.3.9",
+  "version": "0.4.0",
   "description": "The forma command line: render .forma documents to STL, and list what one declares.",
   "keywords": [
     "cli",
@@ -44,6 +44,6 @@
     "check:package": "node scripts/check-package.mjs"
   },
   "dependencies": {
-    "forma-dsl": "^0.3.9"
+    "forma-dsl": "^0.4.0"
   }
 }

package/src/cli.js

@@ -40,6 +40,7 @@ Render options
   -m, --model <name>      which model to build. Defaults to the first declared
       --part <name>       one part by name. Defaults to the only part, or every part union
   -p, --param <name=val>  a value for one declared param. Repeatable
+      --params <file>     a JSON object of values, by name. -p wins over it
       --segments <n>      a fixed segment count for every curve
       --min-angle <deg>   smallest angle between adjacent segments of a curve
       --min-edge <n>      smallest length a curve segment may be shortened to
@@ -61,6 +62,7 @@ const OPTIONS = {
   model: { type: 'string', short: 'm' },
   part: { type: 'string' },
   param: { type: 'string', short: 'p', multiple: true },
+  params: { type: 'string' },
   segments: { type: 'string' },
   'min-angle': { type: 'string' },
   'min-edge': { type: 'string' },
@@ -173,6 +175,41 @@ async function readSource(file) {
   }
 }
 
+/**
+ * Reads a JSON object of parameter values.
+ *
+ * A file rather than a flag per value is what a build matrix wants: the values a variant
+ * needs are a thing you generate, commit and diff, and a shell loop assembling forty `-p`
+ * flags is a worse version of that file.
+ *
+ * Held to an object on purpose. A JSON array or a bare number parses but names nothing, and
+ * `params` the language understands are named.
+ *
+ * @param {string} path The file, which must sit inside the working directory.
+ * @returns {Promise<Record<string, ParameterValue>>} The values, by name.
+ * @throws {UsageError} If it cannot be read, is not JSON, or is not an object.
+ */
+async function parameterFile(path) {
+  let text;
+  try {
+    text = await readFile(await containedPath(path, true), 'utf8');
+  } catch (error) {
+    throw new UsageError(`cannot read ${path}: ${error.message}`);
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new UsageError(`${path} is not valid JSON: ${error.message}`);
+  }
+
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new UsageError(`${path} must hold a JSON object of name/value pairs`);
+  }
+  return parsed;
+}
+
 /**
  * Where an STL goes when `--out` was not given: beside the document, named after it.
  *
@@ -261,7 +298,12 @@ async function renderCommand(file, source, flags, io) {
   try {
     const result = await render(source, {
       model: flags.model ?? null,
-      params: Object.fromEntries((flags.param ?? []).map(parameter)),
+      // The file first, so a `-p` on the command line overrides it. A matrix keeps the
+      // values it shares in the file and varies the one that differs on the line.
+      params: {
+        ...(flags.params ? await parameterFile(flags.params) : {}),
+        ...Object.fromEntries((flags.param ?? []).map(parameter)),
+      },
       maxNodes: numeric(flags['max-nodes'], '--max-nodes') ?? null,
       context,
     });