npm package: @jointhedots/gear
Description: This package exposes the CLI binary `jointhedots-gear` (see `package.json` `bin`).
Latest version: 1.2.3


# jointhedots-gear CLI

This package exposes the CLI binary `jointhedots-gear` (see `package.json` `bin`).

The CLI entrypoint is implemented in `src/cli.ts` and registers these commands:

- `init`
- `make`
- `serve`
- `publish`
- `run`

If a command is invalid, the CLI fails and shows help (`showHelpOnFail(true)` + `.help()`).

## Usage

```bash
jointhedots-gear <command> [options]
```

## Commands

### `init`

Initialize VS Code JSON schema settings.

Behavior implemented in `src/commands/init.ts`:

- Reads `.vscode/settings.json`
- Writes/overrides `json.schemas` with:
	- `application.*` mappings to `./node_modules/@jointhedots/gear/schemas/application.schema.json`
	- `component.*` mappings to `./node_modules/@jointhedots/gear/schemas/component.schema.json`
	- `declaration.*` mappings to `./node_modules/@jointhedots/gear/schemas/declaration.schema.json`

`declaration.*` files are consumed by workspace discovery/build logic (`src/model/helpers/discover-workspace.ts`) and support `.json`, `.yaml`, `.yml`, `.toml` formats (`src/model/helpers/config-loader.ts`).

Arguments: none.

### `make`

Build distributable artifacts (apps, libs, bundles).

Options implemented in `src/commands/make.ts`:

- `--apps <csv>`: app names list, comma-separated (default: `""`)
- `--libs <csv>`: library names list, comma-separated (default: `""`)
- `--bundles <csv>`: bundle names list, comma-separated (default: `""`)
- `--buns <csv>`: alias for `--bundles`
- `--watch`: rebuild on changes (default: `false`)
- `--devmode`: development mode (default: `false`)
- `--clean`: clean output before build (default: `false`)
- `--pack`: request tarball packaging for libraries
- `--versioned <value>`: output version (default: `"*"`)
	- when `"*"`, version is resolved from nearest `package.json` with non-`0.0.0` version
- `--ws <path>`: workspace directory (default: `"."`)
- `--dist <path>`: output directory root (default: `"./dist"`)

Selection behavior:

- `--libs "*"` builds all libraries in workspace
- `--bundles "*"` builds all bundles in workspace
- `--apps` expects explicit CSV names (no `*` branch implemented)

### `serve`

Continuously build one application and optionally start an HTTP server.

Options implemented in `src/commands/serve.ts`:

- `--app <name>`: required application name
- `--devmode`: development mode (default: `false`)
- `--port <number>`: server port (default: `3000`)
- `--versioned <value>`: output version (default: `"*"`)
	- when `"*"`, version is resolved from nearest `package.json` with non-`0.0.0` version
- `--ws <path>`: workspace directory (default: `"."`)
- `--dist <path>`: output directory root (default: `"./dist"`)

Server behavior (when `--port` is truthy):

- serves output files
- exposes `/esbuild` endpoint for build change notifications
- sets `Access-Control-Allow-*` headers to `*`
- logs `http://localhost:<port>`

### `publish`

Build and publish an application to AWS S3.

Options implemented in `src/commands/publish.ts`:

- `--app <name>`: required application name
- `--bucket <name>`: required S3 bucket
- `--region <name>`: AWS region (default: `"eu-north-1"`)
- `--dist <path>`: output directory root (default: `"./dist"`)

Implementation notes from `src/publish/publish_aws_s3.ts`:

- builds app with version marker `"aws_s3"`
- uploads files with `ACL: "public-read"`
- sets `ContentType` from detected MIME type

### `run`

Run a Node entrypoint with file watching and restart logic.

Options implemented in `src/commands/run.ts`:

- `--dir <path>`: required directory to watch
- `--entry <path>`: required program entry path (resolved against `--dir`)
- `--inspect <port>`: enable Node inspector on given port
- `--break`: start inspector in break mode (or use Backspace key for break-mode restart)
- `-- <args...>`: pass remaining arguments to the executed entry program

Runtime behavior:

- watches `--dir` recursively
- on file changes, kills and restarts the child process
- child process is started as:
	- `node --require source-map-support/register --require tsconfig-paths/register --enable-source-maps <entry> ...`
- keyboard controls:
	- `Enter`: restart normally when process is not running
	- `Backspace`: restart in break mode when process is not running
	- `Ctrl+C`: exit monitor

## Environment variables

Only one environment variable is explicitly read in the TypeScript source relevant to CLI build flow:

- `ESBUILD_LOG_LEVEL`
	- used in `src/builder/esbuild-plugins.ts`
	- controls esbuild `logLevel`
	- default is `"silent"` when not set

`process.env.NODE_ENV` is injected by build code as a compile-time define (`"development"` / `"production"`) in `src/builder/esbuild-plugins.ts`; this value is set by CLI build mode logic, not read from shell env by this tool.