create-cs-object 0.1.2 → 0.1.4

package/README.md

@@ -9,6 +9,43 @@ cd my-report
 npm run dev
 ```
 
+In PowerShell 5.1 or 7, select Python 3.11+ and run the setup steps explicitly:
+
+```powershell
+$env:PYTHON = Get-Command python -CommandType Application | Select-Object -First 1 -ExpandProperty Source
+& $env:PYTHON --version
+```
+
+<!-- docs:project-create:start -->
+```powershell
+npm.cmd create cs-object my-report -- --skip-install
+if ($LASTEXITCODE -ne 0) { throw 'Project creation failed.' }
+Set-Location my-report
+```
+<!-- docs:project-create:end -->
+
+<!-- docs:project-setup:start -->
+```powershell
+npm.cmd run setup
+if ($LASTEXITCODE -ne 0) { throw 'Project setup failed.' }
+```
+<!-- docs:project-setup:end -->
+
+<!-- docs:project-dev:start -->
+```powershell
+npm.cmd run dev -- --port 4173
+if ($LASTEXITCODE -ne 0) { throw 'The development server failed.' }
+```
+<!-- docs:project-dev:end -->
+
+Use an absolute Python executable path for `PYTHON` if the interpreter is not
+on PATH. A launcher-only installation can supply that path with
+`$env:PYTHON = py -3.11 -c 'import json, sys; print(json.dumps(sys.executable))' | ConvertFrom-Json`.
+The JSON capture preserves Unicode executable paths under legacy console encodings.
+`PYTHON` is an executable path, not a command such as `py -3.11`.
+The project uses its own `.venv`; activation and execution-policy changes are
+unnecessary. See the generated project's `README.md` for browser and API usage.
+
 The initializer creates an owned project template, installs its exact CLI
 dependency, prepares `.venv`, and installs Chromium. It preserves generated
 files after setup failure; run `npm run setup` in the project to retry.
@@ -25,3 +62,7 @@ through its own local CLI process.
 
 Package tests execute a real npm archive in a temporary consumer. Full runtime
 acceptance belongs to the repository's installed integration checks.
+Before a registry release, use the repository's
+[local archive workflow](../../docs/development.md#local-package-consumers).
+An initializer archive alone still installs the dependency versions named by
+its template; it does not select sibling archives automatically.

package/dist/cli.js

@@ -42,7 +42,7 @@ try {
             typecheck: "tsc -b --pretty false"
           },
           dependencies: {
-            "@cs-object/cli": "0.1.1",
+            "@cs-object/cli": "0.1.2",
             "@cs-object/core": "0.1.0",
             "@base-ui/react": "^1.8.0",
             "@fontsource-variable/geist-mono": "^5.3.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cs-object",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Create a local CalculationSourceObject report project.",
   "license": "Apache-2.0",
   "type": "module",

package/template/.gitattributes

@@ -0,0 +1,2 @@
+*.py text eol=lf
+*.pyi text eol=lf

package/template/AGENTS.md

@@ -15,9 +15,12 @@ and entry function. Restart the local server to update the report menu.
 Read [authoring.md](authoring.md) before changing source or notation. Keep inputs,
 units, assumptions, intermediate steps, references, and outputs inspectable.
 
-Run the calculation with representative inputs and review its rendered report.
+For verification commands and completion criteria, follow
+[Check the result](authoring.md#check-the-result). Run the calculation with
+representative inputs and review its rendered report.
 Report source-to-document consistency, independent numerical agreement, and
 human engineering approval separately. Establish expected reference values
-independently of the execution under test. Inspect every PDF page before delivery.
+independently of the execution under test. When delivering a PDF, inspect every
+page before delivery.
 
 This project runs on localhost. Deployment is outside its calculation workflow.

package/template/README.md

@@ -7,9 +7,13 @@ Node dependencies, creates a private `.venv`, and installs Chromium for PDF outp
 npm run dev
 ```
 
+In PowerShell 5.1 or 7, use `npm.cmd run dev`. Commands that invoke the installed
+CLI directly use `.\node_modules\.bin\cso.cmd`; see
+[Check the result](authoring.md#check-the-result).
+
 Open the localhost address printed in the terminal. Edit numeric inputs in the
-browser, calculate, review the report, and download its PDF. Change formulas in
-`calculations/report.cso.py`, then calculate again. If you change the declared
+browser, calculate, and review the report. Download its PDF when needed. Change
+formulas in `calculations/report.cso.py`, then calculate again. If you change the declared
 inputs, reload the browser page to rebuild its form. Existing report downloads
 remain tied to their captured run until that run expires or the server stops.
 
@@ -29,6 +33,30 @@ reference file. Restart `npm run dev` after editing the list. Each entry gets
 its own verified local API at `/api/reports/<id>/`; the menu switches between
 them without changing the input or report UI code.
 
+For the starter, send inputs to the frontend's `/api/reports/rectangle-area/calculate`
+route. Replace the origin with the address printed by `npm run dev`:
+
+```sh
+curl --fail-with-body http://127.0.0.1:5173/api/reports/rectangle-area/calculate \
+  -H 'Content-Type: application/json' \
+  -d '{"inputs":{"width":2,"height":3}}'
+```
+
+The result is `{"area":6}`. Use the report ID from `reports.json` in place of
+`rectangle-area` after replacing the starter. `POST /api/reports/<id>/runs`
+accepts the same body and returns a captured run with report and download links.
+Wait for the initial report to load before testing input edits in the browser.
+
+In PowerShell 5.1 or 7, the equivalent request avoids native-shell JSON quoting:
+
+```powershell
+$request = @{ inputs = @{ width = 2; height = 3 } } | ConvertTo-Json
+Invoke-RestMethod -Uri 'http://127.0.0.1:5173/api/reports/rectangle-area/calculate' -Method Post -ContentType 'application/json; charset=utf-8' -Body $request
+```
+
+Use the port printed by your development server, such as `4173` when you select
+that port explicitly. The response's `area` property is `6`.
+
 To choose a port, run `npm run dev -- --port 4173`. Use port `0` to select an
 available port. Stop the server with Ctrl+C and use the same command to restart.
 
@@ -36,6 +64,20 @@ If setup failed or you used `--skip-install`, run `npm run setup`.
 Set `PYTHON` to a Python executable if automatic detection cannot find Python
 3.11 or newer. Setup can be run again without replacing calculation files.
 
+In PowerShell, retry with `npm.cmd run setup`. `PYTHON` accepts one absolute
+executable path, including a path with spaces. Use
+`& $env:PYTHON --version` to inspect it. Setup creates `.venv\Scripts\python.exe`.
+You do not need to activate the environment or change an execution policy.
+
+Build the frontend from PowerShell with:
+
+<!-- docs:project-build:start -->
+```powershell
+npm.cmd run build
+if ($LASTEXITCODE -ne 0) { throw 'The frontend build failed.' }
+```
+<!-- docs:project-build:end -->
+
 Before replacing the starter, update [the brief](brief.md), collect
 [references](references/README.md), and read [the authoring notes](authoring.md).
 Source-to-document consistency checks that the documented formulas agree with

package/template/authoring.md

@@ -66,6 +66,12 @@ finite Python floats may use the binary64 range. Booleans are not numeric
 inputs or results. Execution preserves the actual numeric kind and does not
 coerce values to satisfy an annotation.
 
+Numeric input validation checks types and finite values. Documented physical
+ranges, such as positive lengths or a maximum temperature, are assumptions;
+declaring them in the brief does not enforce them in the API or browser.
+Test valid boundary cases and report any physical limits that remain unenforced.
+Record required range enforcement in the brief as an implementation requirement.
+
 ## Supported formulas and content
 
 Supported expressions include finite numeric literals, earlier documented
@@ -121,6 +127,18 @@ function:
 ./.venv/bin/python -m cso_python bindings calculations --check
 ```
 
+In PowerShell 5.1 or 7, use the project's interpreter directly:
+
+<!-- docs:project-bindings:start -->
+```powershell
+$env:PYTHON = Join-Path $PWD '.venv\Scripts\python.exe'
+& $env:PYTHON -I -X utf8 -m cso_python bindings calculations
+if ($LASTEXITCODE -ne 0) { throw 'Binding generation failed.' }
+& $env:PYTHON -I -X utf8 -m cso_python bindings calculations --check
+if ($LASTEXITCODE -ne 0) { throw 'Bindings are stale.' }
+```
+<!-- docs:project-bindings:end -->
+
 For a file `calculations/geometry.cso.py` with a public function
 `rectangle`, a parent in that directory can import and call it:
 
@@ -149,6 +167,11 @@ metadata or public output selections. Formula-only edits may leave the
 interface current. Generation validates definitions but does not execute
 formulas. A missing or stale handle will not regenerate itself.
 
+Save authored Python as UTF-8 with LF line endings. The project's `.gitattributes`
+keeps Python and stub files at LF on Git checkout. Generated bindings already
+use UTF-8/LF. Source hashes cover exact bytes, so an editor's encoding or newline
+change can invalidate a reference even when the formula is unchanged.
+
 Each distinct quantity needs distinct displayed notation. Repeated child
 calls qualify child glyphs using their call names. When a reference
 deliberately reuses a glyph in separate contexts, set a meaningful
@@ -165,15 +188,60 @@ Review every input, unit, intermediate formula, explanation, figure and
 returned result in the report. Check that the displayed substitutions and
 outputs match the intended engineering method.
 
+From the project root, verify one execution and generate checked HTML with the
+project's Python interpreter. In a POSIX shell:
+
+```sh
+PYTHON="$PWD/.venv/bin/python" npx --no-install cso verify calculations/report.cso.py \
+  --function calculate --format json
+mkdir -p output
+PYTHON="$PWD/.venv/bin/python" npx --no-install cso html calculations/report.cso.py \
+  --function calculate --out output/report.html --check-layout --format json
+```
+
+For the unchanged rectangle starter, these PowerShell 5.1 and 7 commands verify
+width 2 and height 3, then write checked HTML and a PDF:
+
+<!-- docs:project-report:start -->
+```powershell
+$env:PYTHON = Join-Path $PWD '.venv\Scripts\python.exe'
+$cso = Join-Path $PWD 'node_modules\.bin\cso.cmd'
+$source = Join-Path $PWD 'calculations\report.cso.py'
+& $cso verify $source --function calculate --input width=2 --input height=3 --format json
+if ($LASTEXITCODE -ne 0) { throw 'Calculation verification failed.' }
+New-Item -ItemType Directory -Force (Join-Path $PWD 'output') | Out-Null
+& $cso html $source --function calculate --input width=2 --input height=3 --out (Join-Path $PWD 'output\report.html') --check-layout --format json
+if ($LASTEXITCODE -ne 0) { throw 'Checked HTML generation failed.' }
+& $cso pdf $source --function calculate --input width=2 --input height=3 --out (Join-Path $PWD 'output\report.pdf') --format json
+if ($LASTEXITCODE -ne 0) { throw 'PDF generation failed.' }
+```
+<!-- docs:project-report:end -->
+
+Use `&` when invoking an executable stored in a variable. These commands use the
+project's installed CLI and managed interpreter, including when the project
+path contains spaces. Setup installs the matching Chromium used by both report
+commands. The [reference recipe](references/README.md#bind-an-independent-case)
+shows how to save structured JSON as UTF-8 without a BOM in either PowerShell.
+
+Repeat verification with `--input name=value` for representative and boundary
+cases. Check each command's exit status and report diagnostics. Open the HTML
+and inspect its content; automated layout checks leave visual inspection pending.
+Use `npm run dev` to test browser input edits and `npm run build` to check the
+frontend. A frontend build alone does not verify the calculation.
+
 Keep three judgments separate: source-to-document consistency, agreement
 with independently established numerical cases, and human engineering
 approval. A pending reference check is not a passing reference check.
+For a bound reference file and browser registration, follow the
+[worked reference recipe](references/README.md#bind-an-independent-case).
 Formula or text edits change captured source identity and can invalidate
 reference bindings; review and explicitly rebind them while preserving
 independently established expected values. Never obtain expected values by
 copying the execution being tested.
 
-Download and inspect every PDF page at normal size for missing steps,
-unreadable notation, clipped content and pagination. The browser and PDF
-need the same run and inputs. See [README.md](README.md) for local setup,
-report registration and UI customization.
+When delivering a PDF, download and inspect every page at normal size for
+missing steps, unreadable notation, clipped content and pagination. The browser
+and PDF need the same run and inputs. HTML-only work can finish with checked
+HTML and visual inspection. Report what passed, failed or was not checked;
+successful generation does not establish human engineering approval.
+See [README.md](README.md) for local setup, report registration and UI customization.

package/template/references/README.md

@@ -3,3 +3,137 @@
 Keep source documents or links here. Record the relevant page or clause, edition,
 and the assumptions each source supports. The starter uses the elementary
 rectangle area relation and has no external engineering reference case.
+
+## Bind an independent case
+
+A CLI reference file contains `referenceVersion: "1"` and a `cases` array.
+Each case records an ID, revision, independent basis, source/input binding,
+and expected values for every calculated symbol, including intermediates.
+Each expected entry needs the captured symbol ID, independently established
+value and matching unit. A comparison of only public outputs is a separate
+numerical check; it does not provide complete CLI reference coverage.
+
+This recipe is for the unchanged rectangle starter. Establish its expected
+area independently first: a 2 m by 3 m rectangle has area 6 m². The verification
+report supplies only source hashes, function and input metadata for binding;
+the expected value below is the hand-derived 6, not a captured result.
+
+From the project root in a POSIX shell:
+
+```sh
+PYTHON="$PWD/.venv/bin/python" npx --no-install cso verify calculations/report.cso.py \
+  --function calculate --input width=2 --input height=3 --format json \
+  > references/rectangle-check.json
+```
+
+Create `references/rectangle-reference.json` with the full case shape:
+
+```sh
+./.venv/bin/python - <<'PY'
+import json
+from pathlib import Path
+
+report = json.loads(Path("references/rectangle-check.json").read_text(encoding="utf-8"))
+if not report["ok"]:
+    raise SystemExit("Resolve verification diagnostics before binding a case")
+fields = (
+    "entryModuleId", "entrySourceHash", "sourceClosureHash", "function",
+    "resolvedInputs", "resolvedInputKinds",
+)
+reference = {
+    "referenceVersion": "1",
+    "cases": [{
+        "id": "rectangle-2-by-3",
+        "revision": "1",
+        "basis": {
+            "method": "Hand-derived rectangle area",
+            "derivation": "Perpendicular sides: 2 m times 3 m equals 6 m^2.",
+            "sourceDescription": "Elementary geometry for the stated rectangle.",
+        },
+        "binding": {name: report["provenance"][name] for name in fields},
+        "expected": [{
+            "symbolId": '["symbol","root","area"]',
+            "value": 6,
+            "unit": "m^2",
+        }],
+    }],
+}
+Path("references/rectangle-reference.json").write_text(
+    json.dumps(reference, indent=2) + "\n", encoding="utf-8", newline="\n"
+)
+PY
+PYTHON="$PWD/.venv/bin/python" npx --no-install cso verify calculations/report.cso.py \
+  --function calculate --input width=2 --input height=3 \
+  --reference references/rectangle-reference.json --format json
+```
+
+In PowerShell 5.1 or 7, run the following block instead. It captures only the
+verification metadata needed to bind the independently derived value `6`.
+The JSON stays inside PowerShell until the file write, so native argument
+quoting cannot alter it. `Join-Path $PWD` gives the .NET writer an absolute path.
+
+<!-- docs:reference-authoring:start -->
+```powershell
+$env:PYTHON = Join-Path $PWD '.venv\Scripts\python.exe'
+$cso = Join-Path $PWD 'node_modules\.bin\cso.cmd'
+$source = Join-Path $PWD 'calculations\report.cso.py'
+$utf8 = [System.Text.UTF8Encoding]::new($false)
+[Console]::OutputEncoding = $utf8
+$reportText = & $cso verify $source --function calculate --input width=2 --input height=3 --format json
+if ($LASTEXITCODE -ne 0) { throw 'Calculation verification failed.' }
+$report = ($reportText -join "`n") | ConvertFrom-Json
+if (-not $report.ok) { throw 'Resolve verification diagnostics before binding a case.' }
+$binding = [ordered]@{}
+foreach ($name in @('entryModuleId', 'entrySourceHash', 'sourceClosureHash', 'function', 'resolvedInputs', 'resolvedInputKinds')) {
+    $binding[$name] = $report.provenance.$name
+}
+$reference = [ordered]@{
+    referenceVersion = '1'
+    cases = @([ordered]@{
+        id = 'rectangle-2-by-3'
+        revision = '1'
+        basis = [ordered]@{
+            method = 'Hand-derived rectangle area'
+            derivation = 'Perpendicular sides: 2 m times 3 m equals 6 m^2.'
+            sourceDescription = 'Elementary geometry for the stated rectangle.'
+        }
+        binding = $binding
+        expected = @([ordered]@{
+            symbolId = '["symbol","root","area"]'
+            value = 6
+            unit = 'm^2'
+        })
+    })
+}
+$referencePath = Join-Path $PWD 'references\rectangle-reference.json'
+$json = ($reference | ConvertTo-Json -Depth 20).Replace("`r`n", "`n") + "`n"
+[System.IO.File]::WriteAllText($referencePath, $json, $utf8)
+& $cso verify $source --function calculate --input width=2 --input height=3 --reference $referencePath --format json
+if ($LASTEXITCODE -ne 0) { throw 'Independent reference verification failed.' }
+```
+<!-- docs:reference-authoring:end -->
+
+This writer produces UTF-8 without a BOM and uses LF. Do not use `>` or
+`Out-File` to save source or JSON in Windows PowerShell 5.1; their default
+encoding differs from this file format. The console encoding assignment makes
+UTF-8 CLI output safe to capture before `ConvertFrom-Json`, including Unicode
+paths and diagnostics.
+
+Check that `checks.independentReferenceAgreement.status` is `passed` with one checked
+symbol. To use the case in the browser, add
+`"reference": "references/rectangle-reference.json"` to the starter entry in
+`reports.json`, restart `npm run dev`, and calculate with width 2 and height 3.
+The same `--reference` option works with `cso html` and `cso pdf`.
+
+For a replacement calculation, establish expected values for all calculated
+symbols from a cited method or independent implementation. Use the symbol IDs
+from its execution evidence, exact documented units, and the binding for that
+source, function and input case. Check the reference against that execution.
+Different inputs need their own cases; an unmatched case is `not_applicable` in
+CLI reports and remains pending in the browser.
+
+Source edits invalidate a binding, including edits to explanation text. After
+reviewing a change, explicitly revise the binding and case revision while
+preserving independently established expected values. Update expected values
+only when their independent derivation changes, and record why. Reference
+agreement does not establish human engineering approval.

package/template/requirements.txt

@@ -1 +1 @@
-cs-object==0.1.0
+cs-object==0.1.1