Merge pull request #57 from classmodel/51-cli

CLI

.github/workflows/deploy.yml

@@ -28,12 +28,19 @@ jobs:
       - name: install
         run: pnpm install --frozen-lockfile
 
-      - name: build
+      - name: Build app
         run: pnpm build
         working-directory: ./apps/class-solid
         env:
           BASE_PATH: "/class-web"
 
+      - name: Build package API docs
+        run: pnpm run docs
+        working-directory: ./packages/class
+
+      - name: Combine web app with api docs
+        run: cp -r ./packages/class/docs ./apps/class-solid/.output/public/docs
+
       - name: upload artifact
         uses: actions/upload-pages-artifact@v3
         with:

.github/workflows/publish-package.yml

@@ -1,4 +1,4 @@
-name: Publish class package
+name: Publish class packages
 
 on:
   release:
@@ -7,18 +7,25 @@ on:
 jobs:
   publish:
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      id-token: write # The OIDC ID token is used for authentication with JSR.
     steps:
-      - uses: pnpm/action-setup@v2
-        with:
-          version: latest
       - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
           node-version: "20"
+          cache: "pnpm"
+          cache-dependency-path: ./pnpm-lock.yaml
+          registry-url: https://registry.npmjs.org/
       - run: pnpm install
-      - run: npx jsr publish --allow-slow-types
+      - run: pnpm build
+        working-directory: packages/class
+      - run: |
+          if [[ $GITHUB_REF_NAME == *next* ]]; then
+            pnpm publish --tag next --no-git-checks
+          else
+            pnpm publish --no-git-checks
+          fi
         working-directory: packages/class
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

.github/workflows/test.yml

@@ -41,6 +41,8 @@ jobs:
           cache-dependency-path: ./pnpm-lock.yaml
       - name: Install dependencies
         run: pnpm install
+      - name: Build packages
+        run: pnpm build --filter '{packages/**}'
       - name: Install Playwright Browsers
         run: pnpm exec playwright install --with-deps chromium
         working-directory: apps/class-solid

.gitignore

@@ -11,6 +11,7 @@ server/dist
 public/dist
 apps/class-solid/.vinxi
 apps/class-solid/.output
+packages/class/docs
 
 # packages/class/.gitignore
 lcov.info

README.md

@@ -2,14 +2,47 @@
 
 [![github repo badge](https://img.shields.io/badge/github-repo-000.svg?logo=github&labelColor=gray&color=blue)]([https://github.com//classmodel/class-web](https://github.com//classmodel/class-web))
 [![Code quality](https://github.com/classmodel/class-web/actions/workflows/quality.yml/badge.svg)](https://github.com/classmodel/class-web/actions/workflows/quality.yml)
-[![JSR](https://jsr.io/badges/@classmodel/class)](https://jsr.io/@classmodel/class)
+[![npmjs.com](https://img.shields.io/npm/v/@classmodel/class.svg?style=flat)](https://www.npmjs.com/package/@classmodel/class)
+[![Checked with Biome](https://img.shields.io/badge/Checked_with-Biome-60a5fa?style=flat&logo=biome)](https://biomejs.dev)
+[![Research Software Directory Badge](https://img.shields.io/badge/rsd-00a3e3.svg)](https://research-software-directory.org/software/class-web)
+[![Documentation](https://img.shields.io/badge/docs-blue)](https://classmodel.github.io/class-web/docs/)
 
 This is an implementation of  the **C**hemistry **L**and-surface **A**tmosphere **S**oil **S**lab (CLASS) model that runs entirely in the browser.
 
-The CLASS web application is available at https://classmodel.github.io/class-web.
-
 For more information on CLASS, see https://classmodel.github.io/.
 
+## Web application
+
+The CLASS web application (from [apps/class-solid](apps/class-solid) directory) is available at https://classmodel.github.io/class-web.
+
+## Command line usage
+
+The class model can be run from the command line.
+The argument is the config file that should adhere to the [JSON schema](./packages/class/src/config.json).
+
+```shell
+# Generate default config file
+pnpx @classmodel/cli generate --output config.json
+
+# Run the model
+pnpx @classmodel/cli run config.json
+# Outputs h variable for each timestep in JSON format
+
+# To output csv use
+pnpx @classmodel/cli run --output output.csv --formtat csv config.json
+
+# To read from stdin use
+cat config.json | pnpx @classmodel/cli -
+```
+
+In development use `pnpx tsx src/cli.ts ./config.json`.
+
+To use the reference configuration of a experiment downloaded from the web application use.
+
+```shell
+jq .reference < ~/Downloads/class-MyExperiment.json  > config.json
+```
+
 ## Developers
 
 This repository is a so-called monorepo, where multiple packages and application
@@ -44,14 +77,12 @@ pnpm json2ts
 
 To publish a new version of the class package:
 
-1. Bump version in `**/package.json` and `packages/class/jsr.json` files. They should all have same version.
+1. Bump version in `**/package.json` files. They should all have same version.
 2. Commit & push changes to main branch.
 3. Create a new [GitHub release](https://github.com/classmodel/class-web/releases)
    - Tag version and title should be the same as the version in the package.json file with `v` prefix.
    - Use `Implementation of the Chemistry Land-surface Atmosphere Soil Slab (CLASS) model that runs entirely in the browser.` as the description with generated release notes.
-4. A GitHub CI workflow will publish the package to [jsr](https://jsr.io/@classmodel/class)
-
-After the workflow has completed the new version will be available on [jsr](https://jsr.io/@classmodel/class).
+4. A GitHub CI workflow will publish the package to [npmjs](https://www.npmjs.com/package/@classmodel/class)
 
 ## Local build
 
@@ -99,6 +130,17 @@ node --import tsx --test --experimental-test-coverage --test-reporter=lcov --tes
 genhtml lcov.info --output-directory coverage
 ```
 
+## API Documentation
+
+The API documention of the package can be generated with
+
+```shell
+pnpm run docs
+```
+Which will write HTML files to `docs/` directory.
+
+The documentation of the latest release is published at [https://classmodel.github.io/class-web/docs/](https://classmodel.github.io/class-web/docs/).
+
 ## Tech stack
 
 The CLASS package is written in typescript.
@@ -109,6 +151,9 @@ of CLASS as well.
 To validate a configuration it uses the JSON schema together with [ajv](https://ajv.js.org/).
 Ajv is the reference JSON schema validator in then JS ecosystem.
 
+The CLI uses [Commander](https://www.npmjs.com/package/commander) to parse the command line arguments.
+Commander is the most popular package for building command line interfaces with sub-command support in Mode.js.
+
 The web application is build with [solid.js](https://docs.solidjs.com/). Solid
 is a relatively simple framework for building reactive web applications. With its
 metaframework [SolidStart](https://docs.solidjs.com/solid-start) it is quite

apps/class-solid/package.json

@@ -1,7 +1,7 @@
 {
   "name": "class-solid",
   "private": true,
-  "version": "0.0.4",
+  "version": "0.0.5",
   "type": "module",
   "scripts": {
     "dev": "vinxi dev",

package.json

@@ -1,6 +1,6 @@
 {
   "private": true,
-  "version": "0.0.4",
+  "version": "0.0.5",
   "scripts": {
     "build": "turbo build",
     "dev": "turbo dev",

packages/class/package.json

@@ -1,28 +1,39 @@
 {
   "name": "@classmodel/class",
-  "version": "0.0.4",
+  "type": "module",
+  "version": "0.0.5",
   "exports": {
     "./class": "./src/class.ts",
+    "./cli": "./dist/cli.js",
     "./config": "./src/config.ts",
     "./config.json": "./src/config.json",
     "./runner": "./src/runner.ts",
     "./bmi": "./src/bmi.ts",
     "./validate": "./src/validate.ts"
   },
+  "files": ["dist"],
   "license": "GPL-3.0-only",
   "scripts": {
+    "dev": "tsc --watch",
+    "build": "tsc",
+    "prepack": "pnpm build",
     "test": "tsx --test src/*.test.ts",
     "typecheck": "tsc --noEmit",
-    "json2ts": "json2ts src/config.json src/config.ts"
+    "json2ts": "json2ts src/config.json src/config.ts",
+    "docs": "typedoc"
   },
+  "bin": "./dist/cli.js",
   "devDependencies": {
+    "@commander-js/extra-typings": "^12.1.0",
     "@types/node": "^20.13.1",
     "json-schema-to-typescript": "^15.0.2",
     "tsx": "^4.16.5",
+    "typedoc": "^0.26.10",
     "typescript": "^5.3.3"
   },
   "dependencies": {
-    "ajv": "^8.17.1"
+    "ajv": "^8.17.1",
+    "commander": "^12.1.0"
   },
   "engines": {
     "node": ">=20.16.0"

packages/class/src/bmi.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { before, describe, test } from "node:test";
-import { BmiClass } from "./bmi";
+import { BmiClass } from "./bmi.js";
 
 describe("BmiClass", () => {
   let bmi: BmiClass;

packages/class/src/bmi.ts

@@ -2,10 +2,9 @@
  * This module contains the Basic Modelling Interface class.
  * @module
  */
-
-import { CLASS } from "./class";
-import type { Config } from "./config";
-import { parse } from "./validate";
+import { CLASS } from "./class.js";
+import type { Config } from "./config.js";
+import { parse } from "./validate.js";
 
 /**
  * A lightweight [Basic Modelling Interface (BMI)](https://bmi.readthedocs.io) like interface for the CLASS model.

packages/class/src/class.test.ts

@@ -1,9 +1,9 @@
 import assert from "node:assert/strict";
 import { describe, test } from "node:test";
 
-import { CLASS } from "./class";
-import { runClass } from "./runner";
-import { parse } from "./validate";
+import { CLASS } from "./class.js";
+import { runClass } from "./runner.js";
+import { parse } from "./validate.js";
 
 describe("CLASS model", () => {
   test("can be instantiated with default config", () => {

packages/class/src/class.ts

@@ -2,7 +2,7 @@
  * This module contains the CLASS model implementation.
  * @module
  */
-import type { Config } from "./config";
+import type { Config } from "./config.js";
 
 // Constants
 const rho = 1.2; /** Density of air [kg m-3] */