package-publish

# package-publish

Use this skill to publish, list, and unpublish private npm packages in the local registry.

## Publishing a package

### Using the lpr CLI (recommended for CI)
```bash
lpr publish ./dist/my-package-1.0.0.tgz
```
Reads the tarball, validates it, stores it in `lpr-packages/published/`, and updates the registry database.

### Using npm publish
```bash
npm publish --registry http://localhost:4873
```
Uses the standard npm publish protocol. Equivalent result to `lpr publish`.

### Using pnpm publish
```bash
pnpm publish --registry http://localhost:4873 --no-git-checks
```

## Publish output

```
reading tarball...
  name     @myco/ui
  version  2.1.0
  scope    @myco
  size     142 KB
  shasum   a1b2c3d4...

storing tarball -> ./lpr-packages/published/@myco/ui/2.1.0.tgz
updating metadata in registry database...

+ @myco/ui@2.1.0
published to http://localhost:4873 in 18ms
```

## Scoped packages

Packages with scopes (e.g., `@myco/ui`) are stored under their scope directory:
```
lpr-packages/published/@myco/ui/2.1.0.tgz
```

To install scoped packages, consumers need the scope mapped in `.npmrc`:
```
@myco:registry=http://localhost:4873
```

This is auto-generated on the Settings page in the web dashboard.

## Listing published packages

```bash
lpr list
```

Output includes: NAME, VERSION, SCOPE, SIZE, PUBLISHED. Or view in the web dashboard at http://localhost:3600.

## Unpublishing a version

```bash
lpr unpublish @myco/ui@2.1.0
```

Removes the tarball from disk and the entry from the registry database. The version will no longer resolve.

## CI/CD workflow

### GitHub Actions example
```yaml
- name: Build package
  run: pnpm run build

- name: Publish to local registry
  run: lpr publish ./dist/my-package-${{ env.VERSION }}.tgz
  env:
    LPR_PORT: 4873
```

### Versioning convention

lpr enforces no version uniqueness constraint by default. Re-publishing the same `name@version` will overwrite the existing tarball. If you want to prevent overwriting, check first:

```bash
# Check if version exists
lpr list | grep "@myco/ui.*2.1.0" && echo "already published"
```

## Storage layout

```
lpr-packages/
  published/
    @myco/
      ui/
        2.1.0.tgz
        2.0.3.tgz
    shared-utils/
      3.0.0.tgz
```

## Publish requirements

- Tarball must be a valid npm package (contains package.json at root)
- `name` and `version` fields are required in package.json
- Tarball file must be readable and non-empty
- Registry must be running (`lpr start`) before publishing via npm/pnpm

## Consuming published packages

After publishing `@myco/ui@2.1.0`, any project with the registry configured can install it:

```bash
# With scope in .npmrc:
npm install @myco/ui

# Or explicitly:
npm install @myco/ui --registry http://localhost:4873
```

The package resolves from the local registry with <5ms latency (served from disk, no network).