Standardize gotap

Author: mmaelicke

README.md

@@ -3,89 +3,67 @@
 [![Docker Image CI](https://github.com/tool-spec/tool_template_node/actions/workflows/docker-image.yml/badge.svg)](https://github.com/tool-spec/tool_template_node/actions/workflows/docker-image.yml)
 [![DOI](https://zenodo.org/badge/564802876.svg)](https://doi.org/10.5281/zenodo.7892415)
 
-This is the template for a generic containerized NodeJS tool following the [Tool Specification](https://tool-spec.github.io/tool-specs/) for reusable research software using Docker.
+Template repository for building a Node.js tool that follows the [Tool Specification](https://tool-spec.github.io/tool-specs/) container contract.
 
-This template can be used to generate new Github repositories from it.
+## How `gotap` works here
 
-Please note that this project has nothing to do with Javascript frontend tools/libs and NodeJS is also not used to
-build some kind of webproject backend stack. We want to integrate NodeJS into a generic workflow runner to make tools available, 
-scientists might be used to from frontend development.
+This template installs [`gotap`](https://github.com/tool-spec/gotap) inside the image and uses it as the default runtime shim:
 
-## How generic?
-
-Tools using this template can be run by the [toolbox-runner](https://github.com/tool-spec/tool-runner). 
-That is only convenience, the tools implemented using this template are independent of any framework.
+```Dockerfile
+CMD ["gotap", "run", "foobar", "--input-file", "/in/input.json"]
+```
 
-The main idea is to implement a common file structure inside container to load inputs and outputs of the 
-tool. The template shares this structures with the [R template](https://github.com/tool-spec/tool_template_r),
-[Python template](https://github.com/tool-spec/tool_template_python)
-and [Octave template](https://github.com/tool-spec/tool_template_octave), but can be mimiced in any container.
+At build time, `gotap generate` creates `parameters.js` from `src/tool.yml`. At runtime, `run.js` uses the generated bindings to validate `/in/input.json`, load parameters and data paths, and write structured run logs.
 
-Each container needs at least the following structure:
+## Required file structure
 
-```
+```text
 /
 |- in/
-|  |- tool.json
+|  |- input.json
 |- out/
 |  |- ...
 |- src/
 |  |- tool.yml
-|  |- run.py
+|  |- run.js
+|  |- parameters.js   (generated at build time)
+|  |- CITATION.cff
 ```
 
-* `tool.json` are parameters. Whichever framework runs the container, this is how parameters are passed.
-* `tool.yml` is the tool specification. It contains metadata about the scope of the tool, the number of endpoints (functions) and their parameters
-* `run.js` is the tool itself, or a NodeJS script that handles the execution. It has to capture all outputs and either `print` them to console or create files in `/out`
+## Build and run
 
+Build the image from the template root:
 
-## How to build the image?
-
-You can build the image from within the root of this repo by
-```
-docker build -t tbr_node_tempate .
+```bash
+docker build -t tbr_node_template .
 ```
 
-Use any tag you like. If you want to run and manage the container with [toolbox-runner](https://github.com/tool-spec/tool-runner)
-they should be prefixed by `tbr_` to be recognized. 
-
-Alternatively, the contained `.github/workflows/docker-image.yml` will build the image for you 
-on new releases on Github. You need to change the target repository in the aforementioned yaml and the repository needs a 
-[personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
-in the repository secrets in order to run properly.
+Run the sample tool:
 
-## How to run?
-
-This template installs a few packages to parse the parameters in the `/in/tool.json`. This assumes that
-the files are not renamed and not moved and there is actually only one tool in the container. For any other case, the environment variables `PARAM_FILE` can be used to specify a new location for the `tool.json` and `TOOL_RUN` can be used to specify the tool to be executed.
-The `run.js` has to take care of that.
-
-To invoke the docker container directly run something similar to:
-```
-docker run --rm -it -v /path/to/local/in:/in -v /path/to/local/out:/out -e TOOL_RUN=foobar tbr_node_template
+```bash
+docker run --rm -it \
+  -v "$(pwd)/in:/in" \
+  -v "$(pwd)/out:/out" \
+  -e TOOL_RUN=foobar \
+  tbr_node_template
 ```
 
-Then, the output will be in your local out and based on your local input folder. Stdout and Stderr are also connected to the host.
+`TOOL_RUN` is only needed when the image contains more than one tool entry. The main runtime interface is still `/in/input.json` plus `gotap run`.
 
-With the toolbox runner, this is simplyfied:
+## Customize
 
-```python
-from toolbox_runner import list_tools
-tools = list_tools() # dict with tool names as keys
-
-foobar = tools.get('foobar')  # it has to be present there...
-foobar.run(result_path='./', foo_int=1337, foo_string="Please change me")
-```
-The example above will create a temporary file structure to be mounted into the container and then create a `.tar.gz` on termination of all 
-inputs, outputs, specifications and some metadata, including the image sha256 used to create the output in the current working directory.
+1. Update `src/tool.yml` to describe your tool.
+2. Add npm or system dependencies in `Dockerfile`.
+3. Implement your tool logic in `src/run.js`.
+4. Rebuild the image so `gotap generate` refreshes `parameters.js`.
 
-## What about real tools, no foobar?
+## Generated bindings and logging
 
-Yeah. 
+The generated `parameters.js` file is not edited by hand. It exposes:
 
-1. change the `tool.yml` to describe your actual tool
-2. add any `npm install` or `apt-get install` needed to the dockerfile
-3. add additional source code to `/src`
-4. change the `run.js` to consume parameters and data from `/in` and useful output in `out`
-5. build, run, rock!
+- `getParameters()`
+- `getData()`
+- `getRunContext()`
+- `getLogger()`
 
+The starter runtime uses `getLogger()` for structured JSON Lines logging while keeping the sample parameter echo on standard output.

src/run.js

@@ -1,14 +1,25 @@
-import { getParameters, getData } from "./parameters.js";
+import { getData, getLogger, getParameters } from "./parameters.js";
 
 const toolName = process.env.TOOL_RUN || "foobar";
 
 const params = getParameters();
 const data = getData();
+const logger = getLogger();
+
+logger.info("start", "Starting tool run", { tool: toolName });
+logger.info("input-loaded", "Loaded validated parameters and data paths", {
+  tool: toolName,
+  parameter_count: Object.keys(params).length,
+  data_keys: Object.keys(data).sort(),
+});
 
 if (toolName === "foobar") {
   console.log("You are running the template directly. Please change the foobar function.");
   console.log(params);
   console.log(data);
+  logger.info("finished", "Template run finished successfully", { tool: toolName });
 } else {
+  logger.error("error", "Requested tool is not implemented in the template", { tool: toolName });
   console.error(`The toolname ${toolName} is not recognized. Did you forget to implement it?`);
+  process.exit(1);
 }