Publishing Packages (init, publish)

Relevant source files

The following files were used as context for generating this wiki page:

• packages/cli/src/commands/init.ts
• packages/cli/src/commands/publish.ts
• packages/cli/src/utils/manifest-loader.ts
• packages/cli/src/utils/tarball-creator.ts
• packages/cli/src/core/package-scanner.ts
• CONTRIBUTING.md

The prpm CLI provides a comprehensive workflow for initializing, validating, and publishing AI prompt packages. The core commands for this lifecycle are prpm init and prpm publish. This process is designed to be both user-friendly for single packages and robust enough for complex multi-package monorepos, with features like automatic package detection, format validation, and resilient registry communication.

The lifecycle begins with prpm init, which creates a prpm.json manifest file. This manifest defines the package's metadata and file structure. Once the manifest is configured, prpm publish bundles the package files into a tarball, validates them, and uploads the package to the PRPM registry, making it available for others to install.

prpm init: Creating a Package Manifest

Sources: packages/cli/src/commands/init.ts

The init command is the entry point for creating a new PRPM package. It generates the prpm.json manifest, which is essential for publishing. The command operates in two primary modes: a "smart" detection mode and a "classic" interactive wizard.

This diagram illustrates the logic flow of the prpm init command.

Smart Initialization (smartInit)

If no prpm.json exists but the directory contains recognizable AI prompt structures (e.g., .cursor/rules, .claude/skills), smartInit takes over. It scans the filesystem, identifies potential packages, and proposes a manifest.

1. Package Scanning: The scanForPackages function searches for files and directories matching known formats.
2. Reconciliation: If a manifest already exists, it reconciles detected packages with the manifest's contents, identifying new, missing, or in-sync packages.
3. User Review: The user can either accept all detected packages in bulk or review them one by one.
4. Manifest Creation: A prpm.json is generated based on the confirmed packages.

Sources: packages/cli/src/commands/init.ts:518-641, packages/cli/src/core/package-scanner.ts

Classic Wizard (classicInit)

If no packages are detected, classicInit provides an interactive wizard to create a manifest from scratch. It prompts the user for:

• Package name, version, description
• Format and subtype (e.g., claude, skill)
• Author and license
• File paths

The wizard can also generate example files and a README.md based on the selected format, providing a quick start for new packages.

Sources: packages/cli/src/commands/init.ts:646-801

Manifest Structure (prpm.json)

The prpm.json file is the source of truth for a package. It can define a single package or multiple packages within a monorepo.

Field	Type	Description
name	string	The unique name of the package.
version	string	The package version (semver).
description	string	A brief description of the package.
format	string	The source format (e.g., cursor, claude).
subtype	string	The package type (e.g., rule, agent, skill).
author	string	The package author.
license	string	The license (e.g., "MIT").
files	string[]	An array of file paths to include in the package.
tags	string[]	Keywords for discoverability.
organization	string	(Optional) The organization to publish under.
private	boolean	(Optional) If true, the package is private.
repository	string	(Optional) The URL of the source code repository.

Sources: CONTRIBUTING.md:20-31, packages/cli/src/commands/init.ts:48-58, packages/cli/src/commands/publish.ts:290-313

prpm publish: Distributing a Package

Sources: packages/cli/src/commands/publish.ts

The publish command is responsible for validating, bundling, and uploading the package to the PRPM registry. It is a multi-step process designed for reliability.

Publishing Workflow

The following sequence diagram shows the key interactions during the prpm publish process.

Pre-Publishing Steps

Before uploading, the CLI performs several local preparation and validation steps:

1. Manifest Loading: It uses findAndLoadManifests to locate and parse prpm.json, .claude/marketplace.json, or .claude-plugin/marketplace.json. This supports single-package and multi-package configurations.
   Sources: packages/cli/src/utils/manifest-loader.ts:113-132, packages/cli/src/commands/publish.ts:159-162
2. Authentication Check: It verifies the user is logged in by checking for a token, unless in CI mode.
   Sources: packages/cli/src/commands/publish.ts:105-113
3. File Validation: It validates that the package's files conform to the declared format's schema using validatePackageFiles.
   Sources: packages/cli/src/commands/publish.ts:333-355
4. Metadata Extraction: It automatically extracts license text from a LICENSE file and a code snippet from the primary package file to enrich the package metadata.
   Sources: packages/cli/src/commands/publish.ts:360-380
5. Tarball Creation: All files listed in the manifest are bundled into a gzipped tar archive (.tgz) using the createTarball function. This single file is what gets uploaded to the registry.
   Sources: packages/cli/src/utils/tarball-creator.ts:25-45, packages/cli/src/commands/publish.ts:384-386

Advanced Publishing Features

The publish command supports several advanced options for complex workflows.

Option	Description
--access <type>	Overrides the manifest's private setting. Can be public or private.
--dry-run	Performs all validation and preparation steps without uploading to the registry.
--package <name>	In a multi-package manifest, publishes only the specified package.
--collection <id>	In a manifest with collections, publishes only the specified collection.
-l, --list	Lists all packages and collections found in the manifest without publishing.

Sources: packages/cli/src/commands/publish.ts:910-925

Organization Publishing

A package can be published under an organization by specifying the organization field in prpm.json. The CLI verifies that the user has the required permissions (owner, admin, or maintainer) for that organization before publishing.
Sources: packages/cli/src/commands/publish.ts:290-321

Resilient Uploads

The publishing client includes a retry mechanism for transient network errors (e.g., 502, 503, ECONNRESET). It will attempt to re-upload the package up to MAX_RETRIES times (default 3) with a delay between attempts. This improves the reliability of publishing in unstable network conditions.
Sources: packages/cli/src/commands/publish.ts:233-244, 417-508

Conclusion

The init and publish commands form a complete and robust system for managing the lifecycle of an AI prompt package. prpm init simplifies the creation of a valid manifest through smart detection and interactive guidance. prpm publish ensures package integrity through a series of validation, metadata extraction, and bundling steps before securely uploading it to the registry. Together, they provide a developer-friendly experience that scales from simple, single-file rules to complex, multi-package organizational repositories.