@git.zone/tspublish 1.9.1 → 1.10.1

package/readme.md

@@ -1,193 +1,375 @@
-# @git.zone/tspublish
+# @git.zone/tspublish 🚀
 
-publish multiple, concise and small packages from monorepos
+> **Effortlessly publish multiple TypeScript packages from your monorepo**
 
-## Install
+[![npm version](https://img.shields.io/npm/v/@git.zone/tspublish.svg)](https://www.npmjs.com/package/@git.zone/tspublish)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-To install `@git.zone/tspublish`, you can use npm. To use the latest stable version, run:
+## 🌟 What is tspublish?
 
-```bash
-npm install @git.zone/tspublish
-```
+`@git.zone/tspublish` is your Swiss Army knife for managing and publishing multiple TypeScript packages from a monorepo. It automates the tedious parts of package publishing while giving you full control over the process. Whether you're maintaining a suite of microservices, a component library, or any collection of related packages, tspublish makes your life easier.
+
+### ✨ Key Features
+
+- 📦 **Automatic Package Discovery** - Scans your monorepo for publishable packages
+- 🎨 **Beautiful CLI Output** - Color-coded logging with progress indicators
+- 🔍 **Version Collision Detection** - Prevents accidental overwrites
+- 🏗️ **Build Integration** - Automatically builds TypeScript before publishing
+- 🎯 **Smart Dependency Management** - Inherits dependencies from your monorepo
+- 🌐 **Multi-Registry Support** - Publish to npm, GitHub packages, or private registries
+- ⚡ **Zero Config** - Works out of the box with sensible defaults
 
-Alternatively, if you are using yarn, the equivalent command would be:
+## 📥 Installation
+
+### As a Development Dependency (Recommended)
 
 ```bash
-yarn add @git.zone/tspublish
-```
+# Using pnpm (recommended)
+pnpm add -D @git.zone/tspublish
+
+# Using npm
+npm install --save-dev @git.zone/tspublish
 
-These commands will add `@git.zone/tspublish` as a dependency in your `package.json` file and install the package into your `node_modules` directory.
+# Using yarn
+yarn add -D @git.zone/tspublish
+```
 
-## Usage
+### Global Installation
 
-`@git.zone/tspublish` is designed to manage the publishing of multiple, small-scale packages within monorepos. The following sections will guide you through its usage, from setting up your environment to effectively publishing packages.
+```bash
+npm install -g @git.zone/tspublish
+```
 
-### Getting Started with TypeScript and Module Setup
+## 🚀 Quick Start
 
-`@git.zone/tspublish` works with monorepos that are organized using TypeScript. The package structure should follow a convention where each submodule intended for publishing is located in a directory prefixed with `ts`, for example, `tsModuleName`. Each submodule directory should contain a `tspublish.json` file to correctly configure the package to be published separately. This file is critical for the `tspublish` process to identify valid package directories and should also include necessary metadata for the package.
+### 1️⃣ Structure Your Monorepo
 
-Your monorepo structure might resemble:
+Organize your packages with the `ts` prefix convention:
 
 ```
-my-monorepo/
-├── ts-package1/
-│   ├── src/
-│   ├── tspublish.json
-├── ts-package2/
-│   ├── src/
-│   ├── tspublish.json
+my-awesome-monorepo/
+├── package.json          # Main monorepo package.json
+├── tsconfig.json         # Shared TypeScript config
+├── ts-core/              # Core package
+│   ├── ts/               # TypeScript source files
+│   ├── readme.md         # Package documentation
+│   └── tspublish.json    # Publishing configuration
+├── ts-utils/             # Utilities package
+│   ├── ts/
+│   ├── readme.md
+│   └── tspublish.json
+└── ts-cli/               # CLI package
+    ├── ts/
+    ├── readme.md
+    └── tspublish.json
 ```
 
-### Configuring `tspublish.json`
+### 2️⃣ Configure Each Package
 
-Each submodule must include a `tspublish.json` within its directory. This JSON file should include essential details for your publishable package, including its dependencies. Here's a basic example of what `tspublish.json` could look like:
+Create a `tspublish.json` in each package directory:
 
 ```json
 {
-  "name": "@myorg/ts-package1",
-  "dependencies": {
-    "some-dependency": "^1.0.0"
-  }
+  "name": "@myorg/core",
+  "order": 1,
+  "dependencies": [
+    "@push.rocks/smartpromise",
+    "@push.rocks/smartfile"
+  ],
+  "registries": [
+    "registry.npmjs.org:public",
+    "npm.pkg.github.com:private"
+  ],
+  "bin": ["my-cli"]
 }
 ```
 
-### Running the CLI
+#### Configuration Options
 
-`@git.zone/tspublish` includes a CLI that simplifies the publishing process. Begin by importing the CLI runner in a script within your project:
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Package name (required) |
+| `order` | number | Build order for interdependent packages |
+| `dependencies` | string[] | Dependencies from the monorepo to include |
+| `registries` | string[] | Target registries with access level |
+| `bin` | string[] | CLI executable names |
 
-```typescript
-import { runCli } from '@git.zone/tspublish';
+### 3️⃣ Run the Publisher
 
-runCli();
+#### Command Line
+
+```bash
+# From your monorepo root
+npx tspublish
 ```
 
-This function call orchestrates the publishing operation. It reads each directory prefixed with `ts`, looks for a `tspublish.json`, and creates an individual package based on the gathered data.
+#### Programmatic Usage
 
-### Core Features
+```typescript
+import { TsPublish } from '@git.zone/tspublish';
 
-#### Publishing Modules
+const publisher = new TsPublish();
+await publisher.publish(process.cwd());
+```
 
-The core functionality provided by `@git.zone/tspublish` involves processing directories to check for valid submodules that are ready to be published. This occurs via the `publish` method in `TsPublish` class. This method does the following:
+## 🎯 Advanced Usage
 
-- **Reads all directories** within the specified monorepo path.
-- **Identifies directories** that start with `ts` and validates the presence of `tspublish.json`.
-- **Logs** information about found packages for user awareness and debugging.
-- **Checks for collisions** with existing versions on the npm registry to prevent overriding published versions.
+### Custom Publishing Pipeline
 
 ```typescript
-import { TsPublish } from '@git.zone/tspublish';
+import { TsPublish, PublishModule } from '@git.zone/tspublish';
+
+// Initialize the publisher
+const publisher = new TsPublish();
 
-const tspublish = new TsPublish();
-await tspublish.publish('/path/to/your/monorepo');
+// Get all publishable modules
+const modules = await publisher.getModuleSubDirs('./my-monorepo');
+
+// Custom processing for each module
+for (const [name, config] of Object.entries(modules)) {
+  const module = new PublishModule(publisher, {
+    monoRepoDir: './my-monorepo',
+    packageSubFolder: name
+  });
+  
+  // Initialize module
+  await module.init();
+  
+  // Create publish directory
+  await module.createPublishModuleDir();
+  
+  // Custom build step
+  console.log(`Building ${config.name}...`);
+  await module.build();
+  
+  // Publish to registries
+  await module.publish();
+}
 ```
 
-#### Package Initialization
+### Registry Configuration
 
-Once valid submodules are identified, the `init` method in the `PublishModule` class initializes the publish module. This includes:
+TSPublish supports multiple registries with different access levels:
 
-- Parsing `tspublish.json` for metadata.
-- Constructing full paths for necessary operations.
-- Verifying package existence to avoid duplication.
+```json
+{
+  "registries": [
+    "registry.npmjs.org:public",        // Public npm package
+    "npm.pkg.github.com:private",       // Private GitHub package
+    "my-company.jfrog.io/npm:restricted" // Corporate registry
+  ]
+}
+```
 
-```typescript
-import { PublishModule } from '@git.zone/tspublish';
+### Build Order Management
+
+When packages depend on each other, use the `order` field to ensure correct build sequence:
 
-const publishModule = new PublishModule({
-  monoRepoDir: '/path/to/monorepo',
-  packageSubFolder: 'ts-package1',
-});
+```json
+// ts-core/tspublish.json
+{
+  "name": "@myorg/core",
+  "order": 1,
+  "dependencies": []
+}
 
-await publishModule.init();
+// ts-utils/tspublish.json
+{
+  "name": "@myorg/utils",
+  "order": 2,
+  "dependencies": ["@myorg/core"]
+}
 ```
 
-#### Creating `package.json`
+### CLI Binary Configuration
 
-Part of the publishing process involves automatically creating a `package.json` tailored to each submodule. This dynamically generated JSON will incorporate dependencies from `tspublish.json` and associate them with the latest version of `tsbuild` from the registry:
+For packages that include CLI tools:
 
-```typescript
-await publishModule.createPackageJson();
+```json
+{
+  "name": "@myorg/cli",
+  "bin": ["my-cli", "my-tool"],
+  "dependencies": ["commander", "chalk"]
+}
 ```
 
-This creates a structured `package.json` which includes scripts to build your TypeScript files before publishing.
+This automatically generates the necessary `cli.js` wrapper and configures the package.json `bin` field.
+
+## 🎨 Beautiful Output
+
+TSPublish provides rich, colored console output with:
+
+- 📊 Progress bars for multi-package operations
+- 🎯 Clear status indicators (ℹ info, ✓ success, ⚠ warning, ✖ error)
+- 📦 Package-specific icons and formatting
+- 🚀 Visual separators between operation phases
+
+## 🔧 How It Works
+
+1. **Discovery Phase** 🔍
+   - Scans for directories starting with `ts`
+   - Validates `tspublish.json` presence
+   - Orders packages by dependency
+
+2. **Preparation Phase** 📋
+   - Creates temporary `dist_publish_*` directories
+   - Generates package.json from tspublish.json
+   - Copies source files and assets
+   - Sets up TypeScript configuration
+
+3. **Build Phase** 🔨
+   - Runs TypeScript compilation
+   - Generates declaration files
+   - Prepares distribution bundle
+
+4. **Validation Phase** ✅
+   - Checks npm registry for existing versions
+   - Prevents accidental overwrites
+   - Validates package metadata
+
+5. **Publishing Phase** 🚀
+   - Publishes to configured registries
+   - Handles authentication
+   - Reports success/failure
+
+## 🤝 Integration with CI/CD
+
+### GitHub Actions
+
+```yaml
+name: Publish Packages
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - uses: pnpm/action-setup@v2
+        with:
+          version: 8
+          
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+          
+      - run: pnpm install
+      
+      - run: pnpm build
+      
+      - run: npx tspublish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
 
-#### Constructing Publish-ready Directory
+### GitLab CI
+
+```yaml
+publish:
+  stage: deploy
+  image: node:20
+  before_script:
+    - npm install -g pnpm
+    - pnpm install
+  script:
+    - pnpm build
+    - npx tspublish
+  only:
+    - tags
+```
 
-After all configurations are verified and the `package.json` is created, the submodule is ready to be published. This step involves setting up a `dist_publish_` directory specific to each module:
+## 📚 API Reference
+
+### TsPublish Class
 
 ```typescript
-await publishModule.createPublishModuleDir();
+class TsPublish {
+  // Publish all packages in a monorepo
+  async publish(monorepoDirPath: string): Promise<void>
+  
+  // Get all publishable module configurations
+  async getModuleSubDirs(dirPath: string): Promise<{[key: string]: ITsPublishJson}>
+}
 ```
 
-The above method ensures that each module's source files are copied and prepared under a dedicated directory meant for packaging and distribution.
+### PublishModule Class
 
-### Logging and Debugging
+```typescript
+class PublishModule {
+  // Initialize the module for publishing
+  async init(): Promise<void>
+  
+  // Create the publishing directory structure
+  async createPublishModuleDir(): Promise<void>
+  
+  // Build the TypeScript package
+  async build(): Promise<void>
+  
+  // Publish to configured registries
+  async publish(): Promise<void>
+}
+```
 
-The package includes a structured logging mechanism using `smartlog` which provides insights into the publishing process, helping in runtime debugging and status tracking of operations:
+### ITsPublishJson Interface
 
 ```typescript
-import { logger } from '@git.zone/tspublish/logging';
-
-logger.log('info', 'Publishing process initialized');
+interface ITsPublishJson {
+  name: string           // Package name
+  order: number          // Build order
+  dependencies: string[] // Dependencies to include
+  registries: string[]   // Target registries
+  bin: string[]         // CLI binaries
+}
 ```
 
-This powerful logging helps in tracking the status of each step and understanding potential issues during the operations.
+## 🐛 Troubleshooting
 
-### Testing with tapbundle
+### Common Issues
 
-To ensure that your publishing workflow is functioning correctly, you can utilize the test suite set up with `tapbundle`. This library facilitates behavior-driven testing for your monorepo. Below is a basic test setup to verify the import and initial function accessibility of `@git.zone/tspublish`:
+**Package already exists with version X.X.X**
+- TSPublish detected a version collision
+- Update your monorepo's package.json version
+- Or unpublish the existing version if appropriate
 
-```typescript
-import { expect, tap } from '@push.rocks/tapbundle';
-import * as tspublish from '@git.zone/tspublish';
+**No publish modules found**
+- Ensure your packages follow the `ts-*` naming convention
+- Check that each package has a valid `tspublish.json`
 
-tap.test('Should run the CLI without errors', async () => {
-  await tspublish.runCli();
-  expect(tspublish).toBeTruthy();
-});
+**Build failures**
+- Verify TypeScript configuration
+- Check that all dependencies are installed
+- Review the build output for specific errors
 
-tap.start();
-```
+## 🔮 Future Features
 
-### Comprehensive usage example
+- 🎯 Selective publishing with pattern matching
+- 🔄 Automatic version bumping strategies
+- 📊 Dry-run mode with detailed preview
+- 🏷️ Git tag integration
+- 📝 Changelog generation
+- 🔐 Enhanced authentication handling
 
-Let's combine all the steps into a complete example where you prepare a monorepo, configure each module, and execute the publishing workflow.
+## License and Legal Information
 
-Suppose you have a project structure as follows:
+This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 
 
-```plaintext
-my-monorepo/
-├── ts-package1/
-│   ├── src/
-│   ├── tspublish.json
-├── ts-package2/
-│   ├── src/
-│   ├── tspublish.json
-```
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
-Follow these steps:
+### Trademarks
 
-1. Ensure each package has `tspublish.json` properly configured with necessary metadata.
-2. Create a CLI script such as `publish.js`:
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
 
-```typescript
-import { runCli } from '@git.zone/tspublish';
-
-runCli()
-  .then(() => {
-    console.log('Publishing completed successfully');
-  })
-  .catch((error) => {
-    console.error('Error during publishing:', error);
-  });
-```
+### Company Information
 
-3. Execute your CLI script:
-
-```bash
-node publish.js
-```
+Task Venture Capital GmbH  
+Registered at District court Bremen HRB 35230 HB, Germany
 
-Your script will call `runCli`, which will traverse each `ts-package`, verify their publish readiness, and handle individual publishing processes.
+For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
 
-By following these comprehensive guidelines and utilizing the structured approach provided by `@git.zone/tspublish`, you can efficiently manage and publish multiple sub-packages from within a monorepo, facilitating organized, modular package management in projects of any scale.
-undefined
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/tspublish',
-  version: '1.9.1',
+  version: '1.10.1',
   description: 'A tool to publish multiple, concise, and small packages from monorepos, specifically for TypeScript projects within a git environment.'
 }

package/ts/classes.giteaassets.ts

@@ -44,37 +44,42 @@ export class GiteaAssets {
     branch?: string
   ): Promise<IRepoFile[]> {
     try {
-      const response = await plugins.smartrequest.request(
-        this.baseUrl + `/repos/${owner}/${repo}/contents/${directory}`,
-        {
-          headers: this.headers,
-          method: 'GET',
-          queryParams: branch ? { ref: branch } : {},
-        }
-      )
-      if (!Array.isArray(response.body) && typeof response.body === 'object') {
-        response.body = [response.body];
-      } else if (Array.isArray(response.body)) {
-        for (const entry of response.body) {
+      const requestBuilder = plugins.smartrequest.SmartRequest.create()
+        .url(this.baseUrl + `/repos/${owner}/${repo}/contents/${directory}`)
+        .headers(this.headers);
+      
+      if (branch) {
+        requestBuilder.query({ ref: branch });
+      }
+      
+      const response = await requestBuilder.get();
+      let responseBody = await response.json();
+      
+      if (!Array.isArray(responseBody) && typeof responseBody === 'object') {
+        responseBody = [responseBody];
+      } else if (Array.isArray(responseBody)) {
+        for (const entry of responseBody) {
           if (entry.type === 'dir') {
             continue;
           } else if (entry.type === 'file') {
-            const response2 = await plugins.smartrequest.request(
-              this.baseUrl + `/repos/${owner}/${repo}/contents/${entry.path}`,
-              {
-                headers: this.headers,
-                method: 'GET',
-                queryParams: branch ? { ref: branch } : {},
-              }
-            );
-            entry.encoding = response2.body.encoding;
-            entry.content = response2.body.content;
+            const requestBuilder2 = plugins.smartrequest.SmartRequest.create()
+              .url(this.baseUrl + `/repos/${owner}/${repo}/contents/${entry.path}`)
+              .headers(this.headers);
+            
+            if (branch) {
+              requestBuilder2.query({ ref: branch });
+            }
+            
+            const response2 = await requestBuilder2.get();
+            const response2Body = await response2.json();
+            entry.encoding = response2Body.encoding;
+            entry.content = response2Body.content;
           }
         }
       }
 
       // lets map to the IRepoFile interface
-      response.body = response.body.map((entry: any) => {
+      responseBody = responseBody.map((entry: any) => {
         return {
           name: entry.name,
           path: entry.path,
@@ -85,7 +90,7 @@ export class GiteaAssets {
         };
       });
 
-      return response.body;
+      return responseBody;
     } catch (error) {
       console.error('Error fetching repository files:', error);
       throw error;

package/ts/classes.publishmodule.ts

@@ -1,6 +1,6 @@
 import * as plugins from './plugins.js';
 import * as paths from './paths.js';
-import { logger } from './logging.js';
+import { logger, logInfo, logSuccess, logWarn, logError, logBuild, logPublish, logOngoing, logStart, logDone } from './logging.js';
 
 import { type ITsPublishJson } from './interfaces/index.js';
 import type { TsPublish } from './classes.tspublish.js';
@@ -66,16 +66,15 @@ export class PublishModule {
     try {
       packageInfo = await smartnpmInstance.getPackageInfo(this.options.name);
     } catch (error) {
-      logger.log('warn', `package does not yet seem to exist. Proceeding in 10 seconds...`);
+      logWarn(`Package ${this.options.name} does not yet seem to exist. Proceeding in 10 seconds...`);
       await plugins.smartdelay.delayFor(10000);
     }
     if (packageInfo) {
       const availableVersions = packageInfo.allVersions.map((versionArg) => versionArg.version);
-      logger.log('info', `available versions are: ${availableVersions.toString()}`);
+      logInfo(`Available versions for ${this.options.name}: ${availableVersions.join(', ')}`);
       if (availableVersions.includes(this.options.version)) {
-        logger.log(
-          'error',
-          `package ${this.options.name} already exists with version ${this.options.version}`
+        logError(
+          `Package ${this.options.name} already exists with version ${this.options.version}`
         );
         process.exit(1);
       }
@@ -162,6 +161,7 @@ export class PublishModule {
   }
 
   public async createPublishModuleDir() {
+    logOngoing(`Creating publish directory for ${this.options.name}`);
     this.options.publishModDirFullPath = plugins.path.join(
       this.options.monoRepoDir,
       `dist_publish_${this.options.packageSubFolder}`
@@ -207,10 +207,12 @@ export class PublishModule {
   }
 
   public async build() {
+    logBuild(`Building ${this.options.name}...`);
     const smartshellInstance = new plugins.smartshell.Smartshell({
       executor: 'bash',
     });
     await smartshellInstance.exec(`cd ${this.options.publishModDirFullPath} && pnpm run build`);
+    logSuccess(`Build completed for ${this.options.name}`);
   }
 
   public async createBinCliSetup() {
@@ -229,6 +231,7 @@ export class PublishModule {
   }
 
   public async publish() {
+    logPublish(`Publishing ${this.options.name} v${this.options.version}...`);
     const smartshellInstance = new plugins.smartshell.Smartshell({
       executor: 'bash',
     });
@@ -242,5 +245,6 @@ export class PublishModule {
         } --no-git-checks --registry https://${registryUrl}`
       );
     }
+    logSuccess(`Successfully published ${this.options.name} v${this.options.version}!`);
   }
 }