# Publish Guide

This guide covers the practical steps for publishing the next npm release of this package.

## Current Assumption

The project is configured to allow npm publication (`"private": false`). The Git remote is **private** (same model as `smart-commit-copilot-cli`): publish the npm package publicly, but do **not** put the private GitHub URL into `package.json` `repository` / `homepage` / `bugs`.

Before you publish, confirm:

- the final package name
- whether the package should be published to npm, GitHub Packages, or stay private

Current package name:

- `smart-commit-host-agent`

Current publish target:

- `0.1.4`

Aligned CLI reference (internal only):

- `peerReference.cliPackage`: `smart-commit-copilot-cli`
- `peerReference.cliVersion`: `0.1.22`

## Pre-Publish Checklist

1. Run `npm test`
2. Run `npm run pack:dry-run`
3. Review [`CHANGELOG.md`](../CHANGELOG.md)
4. Review [`docs/release-checklist.md`](./release-checklist.md)
5. Review the matching release draft in [`docs/releases/0.1.4-draft.md`](./releases/0.1.4-draft.md)

## Recommended Release Order

For the current repository state, the safest order is:

1. update the package version and changelog
2. run the release verification commands
3. create and push a Git tag for the target version
4. create a GitHub Release using the matching release draft text (visible to repo collaborators)
5. log in to npm
6. publish the matching `smart-commit-host-agent` version

This gives you:

- a fixed release checkpoint on the private Git remote
- a stable version label for discussion and changelog references
- a clean follow-up path for npm publication

## Metadata For A Private Source Repo

Keep [`package.json`](../package.json) **without** `repository` / `homepage` / `bugs` while the Git remote stays private. That matches `smart-commit-copilot-cli` and avoids exposing a non-public clone URL on the npm registry page.

README deep links to shipped user docs (`docs/getting-started.md`, `docs/configuration.md`, `docs/integrations.md`, `docs/contracts.md`) should use `cdn.jsdelivr.net/npm/smart-commit-host-agent/...` (not unpkg) so they work after install and browsers receive `Content-Type: …; charset=utf-8` for Markdown.

If the package will be public on npm:

1. confirm the package name is available
2. run `npm publish --access public`

If the package will remain private for now:

- set `"private": true` again before any publish attempt
- continue distributing via source checkout, internal package registry, or tarball

## Dry-Run Packaging

Use:

```bash
npm run pack:dry-run
```

This shows the exact files that would be included in the published tarball, based on the `files` field in [`package.json`](../package.json).

## Release Verification Commands

Run:

```bash
npm test
npm run pack:dry-run
```

Optional local spot-checks:

```bash
npm run build
node out/cli.js --version
node out/cli.js --help
node out/cli.js config resolve --config ./examples/config.host-agent.json
```

## Exact GitHub Release Steps

Create and push the release tag:

```bash
git tag v0.1.4
git push origin v0.1.4
```

Then create a GitHub Release:

- tag: `v0.1.4`
- title: `v0.1.4`
- description: use the content from [`docs/releases/0.1.4-draft.md`](./releases/0.1.4-draft.md)

## Exact npm Publish Steps

Log in first:

```bash
npm login
```

Optional verification:

```bash
npm whoami
```

Publish:

```bash
npm publish --access public
```

If npm 2FA is enabled for publish, use:

```bash
npm publish --access public --otp=XXXXXX
```

Package that will be published:

- `smart-commit-host-agent@0.1.4`

## Suggested Final Verification After Publish

After npm publish succeeds, verify:

```bash
npm view smart-commit-host-agent version
```

Then test a fresh install path:

```bash
npx smart-commit-host-agent@0.1.4 --help
npx smart-commit-host-agent@0.1.4 --version
```