Flow Publish CLI

A command-line tool for publishing JavaScript packages simultaneously on GitHub and the npm registry, with advanced error handling and an interactive interface.

Features

• Simultaneous publication on GitHub and npm
• Advanced error handling with detailed messages
• Interactive user interface
• Automatic rollback in case of failure
• Compatibility with private repositories
• Support for different npm access levels

Installation

# Local installation
npm install

# Global installation
npm install -g .

Configuration

Create a .env file at the root of the project with the following variables:

GITHUB_TOKEN=your_github_token
GITHUB_USERNAME=your_github_username
NPM_TOKEN=your_npm_token
NPM_REGISTRY=https://registry.npmjs.org

Or configure these environment variables in your system.

Usage

Publishing a package

# Interactive publication (with prompts)
flow-publish publish

# Publish on GitHub and npm
flow-publish publish --github --npm --name "my-package" --source ./my-project

# Publish only on GitHub
flow-publish publish --github --no-npm --name "my-package" --source ./my-project

# Publish only on npm
flow-publish publish --no-github --npm --name "my-package" --source ./my-project

# Force publication even if the package already exists
flow-publish publish --force --name "my-package" --source ./my-project

Listing GitHub repositories

# List public GitHub repositories
flow-publish repos

# List all repositories (public and private)
flow-publish repos --all

# Limit the number of results
flow-publish repos --limit 10

# Sort by creation date
flow-publish repos --sort created

Listing npm packages

# List npm packages
flow-publish packages

Unpublish a package

# Unpublish a package from npm
flow-publish unpublish my-package

# Unpublish a specific version from npm
flow-publish unpublish my-package --version 1.0.0

Deleting a package

# Delete from GitHub and npm (with confirmation)
flow-publish delete --name "my-package"

# Delete only from GitHub
flow-publish delete --github --no-npm --name "my-package"

# Delete only from npm
flow-publish delete --no-github --npm --name "my-package"

# Delete a specific version from npm
flow-publish delete --npm --name "my-package" --version "1.0.0"

Common options

• --name: Package/repository name
• --description: Package/repository description
• --source: Package source directory
• --version: npm package version
• --access: npm access level (public/restricted)
• --private: Private GitHub repository
• --github/--no-github: Enable/disable GitHub operations
• --npm/--no-npm: Enable/disable npm operations
• --force: Force publication even if the package already exists

Workflow examples

Developing a new package

1. Create your package locally
2. Publish it on GitHub and npm:

   flow-publish publish --name "my-package" --source ./my-project

Updating an existing package

1. Modify your package locally
2. Update the version in package.json
3. Publish the changes:

   flow-publish publish --name "my-package" --source ./my-project

Publishing Flow Publish CLI itself

If you want to publish or update Flow Publish CLI itself, follow these steps:

Prerequisites

1. Make sure you have GitHub and npm accounts
2. Generate tokens for both platforms:
   • GitHub: https://github.com/settings/tokens (needs repo and packages permissions)
   • npm: https://www.npmjs.com/settings/your-username/tokens

Publishing steps

1. Clone the repository:

   git clone https://github.com/yourusername/flow-publish-cli.git
   cd flow-publish-cli

2. Install dependencies:

   npm install

3. Configure environment variables:

   cp .env.example .env
   # Edit .env with your tokens

4. Make your changes to the codebase

5. Update version in package.json

6. Run tests to ensure everything works:

   npm test

7. Use Flow Publish CLI to publish itself:

   # Make the CLI executable
   chmod +x index.js
      
   # Use the CLI to publish itself
   ./index.js publish --name "flow-publish-cli" --source .

8. Alternatively, publish manually:

   # Publish to GitHub
   git add .
   git commit -m "Release version X.Y.Z"
   git tag vX.Y.Z
   git push origin main --tags
      
   # Publish to npm
   npm publish

Troubleshooting publication

If you encounter issues during publication:

1. Check your tokens and permissions
2. Ensure your package name is unique on npm
3. Verify that your GitHub repository exists and you have write access
4. Check the npm registry status: https://status.npmjs.org/
5. Run with --force if you're updating an existing version (use with caution)

Error handling

Flow Publish CLI includes advanced error handling with:

• Detailed and formatted error messages
• Specific error codes to facilitate debugging
• Automatic rollback in case of partial failure (e.g., if GitHub succeeds but npm fails)
• Input validation before publication

Tests

# Run all tests
npm test

# Run tests with file watching
npm run test:watch

# Generate a coverage report
npm run test:coverage

License

MIT