# Toolprint Providers

[![License](https://img.shields.io/badge/license-EULA-blue.svg)](LICENSE)

This package contains the Toolprint providers.

## License

This software is licensed under the [End User License Agreement (EULA)](LICENSE). By installing or using this software, you agree to be bound by the terms of the license.

## Development Workflow

**TL;DR:**

- This package **must** be published to NPM before or during the CLI's publish process.
- The `workspace:*` protocol in the CLI's `package.json` is for **local development only** and creates a symlink to this package's source code.
- When publishing, `pnpm` automatically replaces `workspace:*` with the correct version from NPM (e.g., `"^0.1.1"`) in the final CLI package.
- Use the `just publish-providers` command to publish this package.

This package is a dependency of the `@toolprint/cli` and is intended to be published to the public NPM registry.

### Workspace Dependency Resolution

During local development, this package is linked to the CLI using the `workspace:*` protocol in the CLI's `package.json`. When you run `pnpm install`, pnpm creates a symlink from the CLI's `node_modules` directory directly to this package's source code.

This is the key benefit of the monorepo setup:

- Any changes you make in this package are instantly available to the CLI.
- There is no need to rebuild or re-install packages after making a change.

### Testing and Debugging with the `package` script

Before publishing to NPM, it's crucial to verify that the package is correctly configured and includes all necessary files. The `package` script serves as a dress rehearsal for publishing.

**1. Create a Local Tarball**

Run the package script from the monorepo root:

```bash
pnpm --filter=@toolprint/providers package
```

This command creates a `.tgz` file in the `packages/providers/pack/` directory. This is the exact file that would be uploaded to NPM.

**2. Test the Package Locally**

To ensure the package works as it would for an end-user, you can install this `.tgz` file in a clean test project:

```bash
# 1. Create and navigate to a temporary test directory outside this project
mkdir /tmp/my-test-app && cd /tmp/my-test-app

# 2. Initialize a new node project
pnpm init

# 3. Install your package using the full path to the .tgz file
pnpm add /path/to/core-ts/packages/providers/pack/toolprint-providers-x.x.x.tgz

# 4. Create and run a test script to import and use your package
```

If your test script runs successfully, you can be confident the package is ready to be published.

### Publishing to NPM

This package **must** be published to NPM for the CLI to be published correctly.

When you run `pnpm publish` on the CLI, pnpm is smart:

1. It sees the `workspace:*` dependency on `@toolprint/providers`.
2. It ensures this package version exists on NPM first. The `just publish-providers` command can be used for this.
3. In the final `package.json` that gets uploaded for the CLI, pnpm **replaces `"workspace:*"` with the actual version number**, like `"@toolprint/providers": "^0.1.1"`.

This ensures that end-users download a working package with standard npm dependencies, while you get the benefit of symlinked local development.