create-cs-object 0.1.1 → 0.1.2

package/README.md

@@ -16,8 +16,12 @@ Existing destinations are never overwritten.
 
 Use `--skip-install` to create files without installing dependencies.
 The generated project contains a synthetic rectangle calculation, an editable
-brief, reference storage, and agent-neutral authoring guidance. The CLI serves
-the browser and report API. The initializer contains no server implementation.
+brief, reference storage, and agent-neutral authoring guidance. Its editable
+React and TypeScript page uses Vite, Tailwind and the selected shadcn preset.
+`npm run dev` starts that page and the CLI calculation and report API on localhost.
+The initializer contains no calculation server implementation.
+The page's navbar report menu reads `reports.json`; each configured report runs
+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.

package/dist/cli.js

@@ -37,9 +37,36 @@ try {
           engines: { node: ">=24" },
           scripts: {
             setup: "npm install && node scripts/setup.ts",
-            dev: "node scripts/dev.ts"
+            dev: "node scripts/dev.ts",
+            build: "tsc -b && vite build",
+            typecheck: "tsc -b --pretty false"
           },
-          dependencies: { "@cs-object/cli": "0.1.0" }
+          dependencies: {
+            "@cs-object/cli": "0.1.1",
+            "@cs-object/core": "0.1.0",
+            "@base-ui/react": "^1.8.0",
+            "@fontsource-variable/geist-mono": "^5.3.0",
+            "@fontsource-variable/raleway": "^5.3.0",
+            "@hugeicons/core-free-icons": "^4.3.5",
+            "@hugeicons/react": "^1.1.10",
+            "@tailwindcss/vite": "^4",
+            "class-variance-authority": "^0.7.1",
+            cn: "^0.4.0",
+            react: "^19.2.8",
+            "react-dom": "^19.2.8",
+            shadcn: "^4.21.0",
+            tailwindcss: "^4",
+            "tw-animate-css": "^1.4.0",
+            vite: "^8",
+            zod: "^4.6.5"
+          },
+          devDependencies: {
+            "@types/node": "^24",
+            "@types/react": "^19",
+            "@types/react-dom": "^19",
+            "@vitejs/plugin-react": "^6",
+            typescript: "^5"
+          }
         },
         null,
         2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cs-object",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Create a local CalculationSourceObject report project.",
   "license": "Apache-2.0",
   "type": "module",
@@ -30,9 +30,12 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.14",
+    "@cs-object/core": "0.1.0",
     "@types/node": "^26",
     "tsup": "^8.5.1",
-    "typescript": "^5"
+    "typescript": "^5",
+    "vite": "^8.3.1",
+    "zod": "^4.6.5"
   },
   "repository": {
     "type": "git",

package/template/AGENTS.md

@@ -6,6 +6,12 @@ the result, units, load case, or acceptance criteria. Record the agreed scope
 in the brief and cite the source of each engineering requirement.
 
 Edit formulas in `calculations/report.cso.py`; the browser edits numeric inputs.
+Edit page layout in `src/App.tsx`, theme tokens in `src/index.css`, and shared UI
+components in `src/components/ui/`. Keep numeric input names and validation
+derived from the Python definition. Add shadcn components with
+`npx shadcn@latest add <component>`.
+Add each runnable report to `reports.json` with a unique ID, title, source path
+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.
 

package/template/README.md

@@ -13,6 +13,22 @@ browser, calculate, review the report, and download its PDF. Change formulas in
 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.
 
+Customize the page in `src/App.tsx` and its theme in `src/index.css`. The
+components in `src/components/ui/` are owned by this project. To add another
+shadcn component, run `npx shadcn@latest add <component>` and edit the page to
+use it. `components.json` records the chosen Vite, Base UI and Lyra preset.
+The input fields still come from the Python definition; page edits do not change
+the calculation or API validation. `npm run build` checks and builds the Vite
+frontend, but the local API and PDF routes still require `npm run dev`.
+
+The navbar menu lists runnable reports from [reports.json](reports.json).
+To add one, put its `.cso.py` source under `calculations/` and add an entry with
+a unique URL-safe `id`, a display `title`, the relative `source` path and its
+entry `function`. Add `reference` when the report has an independent numerical
+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.
+
 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.
 

package/template/authoring.md

@@ -1,18 +1,179 @@
-# Write scalar calculations
-
-Use constrained Python in `calculations/report.cso.py`. Declare documented inputs
-and assignments with `Annotated[float, symbol(...)]` or
-`Annotated[int, symbol(...)]`. A plain `float` or `int` parameter needs a separate
-documented `given()` assignment.
-Use descriptive names and qualified glyphs such as `A_{rect}`. Define units and
-explain each glyph qualifier. Return a dictionary that selects documented values.
-
-Use finite scalar numbers and arithmetic `+`, `-`, `*`, `/`, and `**`.
-Python booleans are not numeric inputs. Declare `float` for fractional results.
-Exact integers must fit within ±(2**53 - 1). Keep assumptions and references in
-literal `text(id=..., content=...)` calls so they appear in the report.
-
-The [maintained authoring guide](https://github.com/viktar-b/CalculationSourceObject/blob/main/docs/authoring.md)
-describes supported functions, composition, and document content. Unsupported
-Python constructs must be replaced with supported scalar expressions before
-the calculation can pass verification.
+# Author calculations
+
+This guide ships with the generated project. Write constrained Python in
+`calculations/*.cso.py`; the installed `cs-object` package captures the same
+source for numerical execution and the report. Start with
+[`calculations/report.cso.py`](calculations/report.cso.py), then replace the
+rectangle example with the calculation in [brief.md](brief.md). Keep the
+brief, sources and reviewable report consistent.
+
+## Before writing formulas
+
+State the purpose, input ranges, units, assumptions, required outputs and
+acceptance cases in [brief.md](brief.md). Keep source documents or links under
+[`references/`](references/README.md), with the edition, page or clause and the
+assumption each supports. Ask for a decision when a missing assumption would
+change the result. Establish expected numerical values independently of the
+calculation being checked; formula agreement alone does not establish
+engineering correctness.
+
+## Define a report
+
+The starter shows the full pattern:
+
+```python
+from typing import Annotated
+from cso_python import calculation, section, symbol, text
+
+
+@calculation(id="rectangle-area", title="Rectangle area")
+@section(title="Rectangle", root=True)
+def calculate(
+    width: Annotated[float, symbol(glyph="w_{rect}", description="Rectangle width", unit="m")] = 2.0,
+    height: Annotated[float, symbol(glyph="h_{rect}", description="Rectangle height", unit="m")] = 3.0,
+):
+    text(id="assumptions", content="Assume perpendicular sides and positive dimensions. The qualifier rect means rectangle.")
+    text(id="reference", content="Area equals width multiplied by height; see brief.md for the project scope.")
+    area: Annotated[float, symbol(glyph="A_{rect}", description="Rectangle area", unit="m^2")] = width * height
+    return {"area": area}
+```
+
+Each runnable function needs `@calculation`, `@section`, documented numeric
+parameters and a final dictionary of public results. Put arithmetic in
+annotated assignments before the return. The return selects existing
+quantities; it does not replace their documented formula rows. Source order
+sets report order, while return order sets the public output order. Intermediate
+annotated quantities remain in the report even when they are not returned.
+
+Use descriptive Python names such as `total_area`, not one-letter identifiers.
+Give every quantity a glyph, description and unit. Qualify variable glyphs,
+including diagram labels: `A_{rect}`, `w_{pan}` and `\rho_{mat}` distinguish
+their meanings. Explain qualifiers in the report. Standard unit symbols such as
+`m` and `kg` need no qualifier. Use raw strings for backslash Greek names,
+for example `r"\rho_{mat}"`. The notation parser is not a LaTeX engine:
+`\mathrm` and `\frac` are unsupported. When reproducing an identified
+external calculation, its original glyphs may be retained with a recorded
+source URL and explanation of any repeated notation.
+
+Signature metadata creates an input row, including when the parameter is not
+used in a formula. A plain `float` or `int` parameter instead needs one
+annotated `given(parameter)` assignment; do not document the same parameter
+both ways. Give inputs finite literal defaults. Declare `float` when division
+or another operation can produce a fractional value. An `int` declaration
+requires an actual Python integer; a `float` declaration accepts finite
+Python integers and floats. Exact integers must fit within ±(2**53 - 1);
+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.
+
+## Supported formulas and content
+
+Supported expressions include finite numeric literals, earlier documented
+quantities, unary minus, `+`, `-`, `*`, `/`, `**`, `sqrt`, `math.pi`, `ceil`,
+`floor`, `exp`, `log`, `abs`, `min`, `max`, `round`, trigonometric functions,
+`atan2` and `hypot`. Import math functions from `math` or call them through
+`math`. Trigonometric functions use radians; declare angle units explicitly.
+`log(value)` is natural logarithm. `round` follows Python's ties-to-even
+behavior for represented binary64 values. Invalid domains and non-finite
+results fail verification.
+
+Numeric conditional expressions can use `<`, `<=`, `>`, `>=`, `==`, `!=`,
+comparison chains and `and` / `or` between comparisons. Only the chosen
+numeric branch executes. Bare numeric conditions, boolean quantities,
+`value or fallback`, iterable or keyword forms of `min` / `max` / `hypot`,
+and arbitrary Python statements are outside the supported source subset.
+Run the calculation to detect unsupported syntax; a valid Python expression
+is not necessarily a supported documented formula. This is trusted local
+authoring, not a sandbox for untrusted Python.
+
+Place literal `text(id=..., content=...)` calls beside the formulas they
+explain. Document assumptions, limits and reference clauses in the report,
+not only in comments. `figure(...)` accepts a module-relative PNG, JPEG or
+SVG path, caption and alt text. Keep the asset inside the calculation
+directory, for example `calculations/assets/section.svg`:
+
+```python
+from cso_python import figure
+
+figure(
+    id="section-diagram",
+    path="assets/section.svg",
+    media_type="image/svg+xml",
+    caption="Section dimensions and axes",
+    alt="Dimensioned section with x and y axes",
+)
+```
+
+Missing or invalid assets fail instead of silently disappearing. A
+`with document_section(id="...", title="..."):` block can group one level
+of symbols, text and figures. Nested groups, calculation calls and returns
+do not belong inside that block.
+
+## Reuse calculations
+
+Keep common `Annotated` metadata or `TypeAlias` declarations in a local
+Python module, then use the same alias for a quantity passed between
+calculations. Generate typed handles before importing another `.cso.py`
+function:
+
+```sh
+./.venv/bin/python -m cso_python bindings calculations
+./.venv/bin/python -m cso_python bindings calculations --check
+```
+
+For a file `calculations/geometry.cso.py` with a public function
+`rectangle`, a parent in that directory can import and call it:
+
+```python
+from _cso_bindings.geometry import rectangle
+
+first_panel = rectangle(width=width, height=first_panel_height)
+second_panel = rectangle(width=width, height=second_panel_height)
+total_area: TotalPanelArea = first_panel["area"] + second_panel["area"]
+```
+
+`TotalPanelArea` must be declared in the shared metadata module. Calls take
+named arguments. Each call adds a child section at its source location;
+documented intermediate results stay visible even if the child does not
+select them as public outputs. Forwarded quantities retain their identity,
+description, glyph and unit. Callee units must match exactly; write an
+explicit annotated conversion when needed. Equal numeric values do not make
+two quantities identical.
+
+Generate bindings from a directory containing the parent and its local
+dependencies. Source paths below it must use Python identifiers, such as
+`steel_sections/calculate.cso.py`. Imports follow those paths. The generated
+`_cso_bindings/` directory must exist at runtime; do not edit its files.
+Regenerate after changing parameters, numeric declarations, defaults,
+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.
+
+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
+`notation_scope` in `symbol(...)` and explain that scope in a description or
+section title. Collisions within one scope fail.
+
+## Check the result
+
+Add each top-level runnable function to [reports.json](reports.json) with its
+ID, title, source path and function name, then restart `npm run dev`. The
+browser derives editable inputs from the Python definition and calls the
+verified local API. Recalculate with representative and boundary inputs.
+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.
+
+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.
+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.

package/template/components.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-lyra",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/index.css",
+    "baseColor": "taupe",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "hugeicons",
+  "rtl": false,
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "menuColor": "default-translucent",
+  "menuAccent": "subtle",
+  "registries": {}
+}

package/template/gitignore

@@ -1,4 +1,5 @@
 node_modules/
+dist/
 .venv/
 __pycache__/
 _cso_bindings/

package/template/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Calculation report</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/reports.json

@@ -0,0 +1,8 @@
+[
+  {
+    "id": "rectangle-area",
+    "title": "Rectangle area",
+    "source": "calculations/report.cso.py",
+    "function": "calculate"
+  }
+]

package/template/scripts/dev.ts

@@ -1,4 +1,4 @@
-import { spawn } from 'node:child_process';
+import { spawn, type ChildProcess } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
@@ -10,48 +10,119 @@ const python = join(
   '.venv',
   process.platform === 'win32' ? 'Scripts/python.exe' : 'bin/python',
 );
-try {
+
+function awaitOrigin(child: ChildProcess): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let stdout = '';
+    const finish = (error?: Error, origin?: string) => {
+      clearTimeout(timeout);
+      child.off('error', onError);
+      child.off('exit', onExit);
+      child.stdout?.off('data', onData);
+      if (error) reject(error);
+      else if (origin) resolve(origin);
+    };
+    const onError = (error: Error) => finish(error);
+    const onExit = (code: number | null) =>
+      finish(new Error(`Calculation server exited (${code})`));
+    const onData = (chunk: string) => {
+      stdout += chunk;
+      const match = /CSO dev (http:\/\/127\.0\.0\.1:\d+)/.exec(stdout);
+      if (match?.[1]) finish(undefined, match[1]);
+    };
+    const timeout = setTimeout(
+      () => finish(new Error('Calculation server did not start')),
+      30_000,
+    );
+    child.once('error', onError);
+    child.once('exit', onExit);
+    child.stdout?.setEncoding('utf8');
+    child.stdout?.on('data', onData);
+  });
+}
+
+async function main() {
   if (!existsSync(python))
     throw new Error(
       'Run npm run setup to prepare the project Python environment.',
     );
+  const { loadReports } = await import('./reports.ts');
+  const args = process.argv.slice(2);
+  if (args.length !== 0 && (args.length !== 2 || args[0] !== '--port'))
+    throw new Error('Usage: npm run dev -- [--port 0-65535]');
+  const spelling = args[1] ?? '5173';
+  if (!/^\d+$/.test(spelling) || Number(spelling) > 65535)
+    throw new Error('--port must be an integer between 0 and 65535');
+  const port = Number(spelling);
+  const reports = loadReports(project);
   const require = createRequire(import.meta.url);
   const cli = join(
     dirname(require.resolve('@cs-object/cli/package.json')),
     'dist/cli.js',
   );
-  const child = spawn(
-    process.execPath,
-    [
-      cli,
-      'dev',
-      'calculations/report.cso.py',
-      '--function',
-      'calculate',
-      ...process.argv.slice(2),
-    ],
-    {
-      cwd: project,
-      env: { ...process.env, PYTHON: python },
-      stdio: 'inherit',
-    },
-  );
-  const interrupt = () => child.kill('SIGINT');
-  const terminate = () => child.kill('SIGTERM');
-  process.on('SIGINT', interrupt);
-  process.on('SIGTERM', terminate);
-  child.once('error', (error) => {
-    process.stderr.write(`${error.message}\n`);
-  });
-  child.once('close', (code, signal) => {
-    process.off('SIGINT', interrupt);
-    process.off('SIGTERM', terminate);
-    process.exitCode =
-      code ?? (signal === 'SIGINT' ? 130 : signal === 'SIGTERM' ? 143 : 1);
-  });
-} catch (error) {
+  const children: ChildProcess[] = [];
+  let vite: Awaited<ReturnType<typeof import('vite').createServer>> | undefined;
+  let stopping = false;
+  const stop = () => {
+    if (stopping) return;
+    stopping = true;
+    for (const child of children) child.kill('SIGTERM');
+    if (vite) void vite.close();
+  };
+  process.on('SIGINT', stop);
+  process.on('SIGTERM', stop);
+  try {
+    const backends = [];
+    for (const report of reports) {
+      const child = spawn(
+        process.execPath,
+        [
+          cli,
+          'dev',
+          report.source,
+          '--function',
+          report.function,
+          ...(report.reference ? ['--reference', report.reference] : []),
+          '--port',
+          '0',
+        ],
+        {
+          cwd: project,
+          env: { ...process.env, PYTHON: python },
+          stdio: ['ignore', 'pipe', 'inherit'],
+        },
+      );
+      children.push(child);
+      const origin = await awaitOrigin(child);
+      child.once('exit', (code) => {
+        if (stopping) return;
+        process.stderr.write(
+          `Calculation server for ${report.id} exited (${code}).\n`,
+        );
+        process.exitCode = code || 1;
+        stop();
+      });
+      backends.push({ id: report.id, title: report.title, origin });
+    }
+    process.env.CSO_REPORT_BACKENDS = JSON.stringify(backends);
+    const { createServer } = await import('vite');
+    vite = await createServer({
+      server: { host: '127.0.0.1', port, strictPort: port !== 0 },
+    });
+    await vite.listen();
+    const address = vite.httpServer?.address();
+    if (!address || typeof address === 'string')
+      throw new Error('Vite has no localhost address');
+    process.stdout.write(`CSO dev http://127.0.0.1:${address.port}\n`);
+  } catch (error) {
+    stop();
+    throw error;
+  }
+}
+
+main().catch((error: unknown) => {
   process.stderr.write(
     `${error instanceof Error ? error.message : String(error)}\n`,
   );
   process.exitCode = 1;
-}
+});

package/template/scripts/reports.ts

@@ -0,0 +1,24 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { PythonIdentifierSchema } from '@cs-object/core';
+import { z } from 'zod';
+
+const ReportSchema = z.strictObject({
+  id: z.string().regex(/^[a-z][a-z0-9-]*$/),
+  title: z.string().min(1),
+  source: z.string().regex(/^calculations\/(?!.*\.\.\/)[^/].*\.cso\.py$/),
+  function: PythonIdentifierSchema,
+  reference: z.string().optional(),
+});
+
+export type Report = z.infer<typeof ReportSchema>;
+
+export function loadReports(project: string): Report[] {
+  const reports = z
+    .array(ReportSchema)
+    .min(1)
+    .parse(JSON.parse(readFileSync(join(project, 'reports.json'), 'utf8')));
+  if (new Set(reports.map(({ id }) => id)).size !== reports.length)
+    throw new Error('reports.json contains duplicate report IDs');
+  return reports;
+}