# CLI Publishing

The repository root is a private development package for the web app, backend,
tests, and build tooling. The public npm package is generated into `dist/npm`
and contains only the bundled `makefx` executable, README, and publish manifest.

## Build The Publish Package

```bash
pnpm run build:cli
```

This produces:

- `dist/cli/makefx.mjs` - bundled executable used locally
- `dist/npm/makefx.mjs` - executable copied into the npm package
- `dist/npm/package.json` - public publish manifest with no runtime dependencies
- `dist/npm/README.md` - npm-facing CLI README generated by `scripts/package-cli.mjs`

The root `README.md` describes the full app repository. The npm README should
stay focused on installed CLI users: install, auth, project binding, common
commands, JSON/script usage, troubleshooting, and docs links.

Check the package contents before publishing:

```bash
pnpm run pack:cli
```

## Raise The Version

The npm version comes from root `package.json`. Bump it on a normal branch,
commit the change, and merge it to `main`.

```bash
pnpm run version:cli:patch
pnpm run version:cli:minor
pnpm run version:cli:major
```

Use `patch` for fixes to existing CLI behavior:

- broken command behavior
- auth, upload, download, follow, or WebSocket reliability fixes
- generated npm package fixes such as README, metadata, or dependency cleanup
- help text corrections that do not change command semantics

Use `minor` for additive CLI behavior:

- new commands or subcommands
- new flags or output fields
- new supported media workflows
- better script/agent support that remains backward compatible

Use `major` for breaking CLI behavior:

- removing or renaming commands, flags, or JSON fields
- changing default environments or output formats
- changing `.inventory/config.json` in a non-compatible way
- requiring a newer Node major version

Do not bump the CLI version for website-only, backend-only, deploy-only, or
internal test/build changes unless the published `makefx` package changes as a
result.

## Publish From CI

Publishing runs automatically after a push to `main`. The workflow reads the
root `package.json` version and checks npm before doing any build work:

- if `makefx@VERSION` already exists, the workflow exits successfully without
  publishing
- if `makefx@VERSION` is missing, the workflow builds and publishes `./dist/npm`

`.github/workflows/publish-cli.yml` builds the dist-only package, verifies that
it has no runtime dependencies, and publishes `./dist/npm`.

The publish workflow intentionally runs on `ubuntu-latest` because npm Trusted
Publishing requires a GitHub-hosted runner. Keep it short: it should install,
run `pnpm run build:cli`, verify the lean package, and publish. Do not run
`pnpm run ci:pre-push` or component/full test suites there; those belong to the
self-hosted CI runner.

Configure npm Trusted Publishing for:

- package: `makefx`
- GitHub repository: `krasnoperov/inventory`
- workflow filename: `publish-cli.yml`
- allowed action: `npm publish`

The workflow can also be run manually from GitHub Actions, but it must run from
`main`. It uses `main`'s `package.json` version and applies the same "publish
only if missing" guard.

## Manual Fallback

For emergency local publishing from an authenticated npm account:

```bash
pnpm run publish:cli
```

Prefer CI for normal releases so the npm package is tied to a GitHub tag and
build provenance.