npm package: @godspeedsystems/gs-tool
Description: A CLI runner for executing and validating tools in the Godspeed ecosystem.
Latest version: 0.12.4

# @godspeedsystems/gs-tool

A CLI runner for executing and validating tools in the Godspeed ecosystem.

---

## Prerequisites

- Node.js 18+

---

## Installation

You don't need to install this tool globally. Instead, run it directly with `npx`:

```bash
npx @godspeedsystems/gs-tool tool-name --option-1 value1 --option-2 value2
```

This command resolves and runs a tool located under `tools/tool-name`, handling validation and dependencies for you.

---

## Description

`gs-tool` is a generic interface for executing any scaffolded tool in the monorepo. It performs schema-based input/output validation and ensures all prerequisites are met before the tool runs. This allows tool creators to focus on business logic while the runner handles safety, conformity, and dependency guarantees.

---

## What this tool does

This tool is invoked using:

```bash
npx @godspeedsystems/gs-tool tool-name --option-1 types.ts --option-2 typescript
```

Here, `tool-name` refers to the specific tool you want to run, and the `--option` flags are passed directly to it.

When invoked, the tool:

- Validates the input `--option-*` values against the input schema defined in `tools/tool-name/specs.yaml`
- Executes the logic defined by the selected tool
- Validates the output (`output.data`) using the `output-json` schema from `specs.yaml`
- Parses the list of prerequisite packages from `tools/tool-name/README.md` and installs any missing ones into the user’s project
- Returns the tool’s output after all validations and dependency handling are complete

This ensures schema-compliant input/output, auto-installation of missing dependencies, and a consistent tool execution experience across projects.

### If you want to list the tools available in the Godspeed ecosystem

You can use the `gs-tool list` command to list all available tools:

```bash
npx @godspeedsystems/gs-tool list
```

```bash
Usage: gs-tool list [options]

Options:
  -l --long    Show long list
  -m --medium  Show medium list
  -s --short   Show short list
  -h, --help   display help for command
```

### If you want to get more information about a specific tool

You can use the `gs-tool tool-name --info` command to get more information about a specific tool:

```bash
npx @godspeedsystems/gs-tool tool-name --info
```

### If you want to run a tool with custom input

You can use the `gs-tool tool-name --input-json '{"key": "value"}'` command to run a tool with custom input:

```bash
npx @godspeedsystems/gs-tool tool-name --input-json '{"key": "value"}'
```

### If you want to run a tool with custom input from a file

You can use the `gs-tool tool-name --input-json input.json` command to run a tool with custom input from a file:

```bash
npx @godspeedsystems/gs-tool tool-name --input-json input.json
```

---

## What this tool does NOT do

- It does not persist any state between runs (every execution is stateless)
- It does not handle environment-specific configuration overrides
- It does not support custom schema formats outside JSON Schema (as defined in `specs.yaml`)

---

## Future Enhancements