v4.1.0

changelog.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2026-01-04 - 4.1.0 - feat(docs)
+update README with improved docs and monorepo/tspublish guidance; namespace and extend npmextra.json with release registries; bump several dependencies
+
+- Bumped dependencies: @git.zone/tspublish ^1.10.3 → ^1.11.0, @push.rocks/smartfs ^1.2.0 → ^1.3.1, @git.zone/tstest ^3.1.3 → ^3.1.4, @types/node ^25.0.1 → ^25.0.3
+- npmextra.json reorganized: replaced legacy keys with namespaced entries (@git.zone/cli, @git.zone/tsdoc) and added @ship.zone/szci; added release configuration with registries [https://verdaccio.lossless.digital, https://registry.npmjs.org] and public accessLevel
+- README rewritten: improved formatting, added emojis and tables, new 'Issue Reporting and Security' section, monorepo/tspublish usage docs, auto-unpack and decorator guidance, CI/CD and troubleshooting improvements
+- Non-breaking changes; recommended next semantic version bump is minor
+
 ## 2025-12-14 - 4.0.2 - fix(TsCompiler)
 Clear output directories before compilation to ensure clean builds and avoid stale files
 

npmextra.json

@@ -1,9 +1,5 @@
 {
-  "npmci": {
-    "npmGlobalTools": [],
-    "npmAccessLevel": "public"
-  },
-  "gitzone": {
+  "@git.zone/cli": {
     "projectType": "npm",
     "module": {
       "githost": "gitlab.com",
@@ -23,9 +19,19 @@
         "development",
         "API"
       ]
+    },
+    "release": {
+      "registries": [
+        "https://verdaccio.lossless.digital",
+        "https://registry.npmjs.org"
+      ],
+      "accessLevel": "public"
     }
   },
-  "tsdoc": {
+  "@git.zone/tsdoc": {
     "legal": "\n## License and Legal Information\n\nThis 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. \n\n**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.\n\n### Trademarks\n\nThis 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.\n\n### Company Information\n\nTask Venture Capital GmbH  \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy 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.\n"
+  },
+  "@ship.zone/szci": {
+    "npmGlobalTools": []
   }
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git.zone/tsbuild",
-  "version": "4.0.2",
+  "version": "4.1.0",
   "private": false,
   "description": "A tool for compiling TypeScript files using the latest nightly features, offering flexible APIs and a CLI for streamlined development.",
   "main": "dist_ts/index.js",
@@ -36,12 +36,12 @@
   },
   "homepage": "https://code.foss.global/git.zone/tsbuild#README",
   "dependencies": {
-    "@git.zone/tspublish": "^1.10.3",
+    "@git.zone/tspublish": "^1.11.0",
     "@push.rocks/early": "^4.0.4",
     "@push.rocks/smartcli": "^4.0.19",
     "@push.rocks/smartdelay": "^3.0.5",
     "@push.rocks/smartfile": "^13.1.2",
-    "@push.rocks/smartfs": "^1.2.0",
+    "@push.rocks/smartfs": "^1.3.1",
     "@push.rocks/smartlog": "^3.1.10",
     "@push.rocks/smartpath": "^6.0.0",
     "@push.rocks/smartpromise": "^4.2.3",
@@ -49,8 +49,8 @@
   },
   "devDependencies": {
     "@git.zone/tsrun": "^2.0.1",
-    "@git.zone/tstest": "^3.1.3",
-    "@types/node": "^25.0.1"
+    "@git.zone/tstest": "^3.1.4",
+    "@types/node": "^25.0.3"
   },
   "files": [
     "ts/**/*",

readme.md

@@ -1,8 +1,12 @@
 # @git.zone/tsbuild
 
-A powerful, modern TypeScript build tool with smart defaults, full tsconfig.json support, and automatic output directory management.
+A powerful, modern TypeScript build tool with smart defaults, full tsconfig.json support, and automatic output directory management. 🚀
 
-## Install
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## 📦 Install
 
 ```bash
 # Using pnpm (recommended)
@@ -12,20 +16,22 @@ pnpm install @git.zone/tsbuild --save-dev
 npm install @git.zone/tsbuild --save-dev
 ```
 
-## Why tsbuild?
+## ⚡ Why tsbuild?
 
-- **Smart tsconfig.json Integration** - Respects all your compiler options with intelligent merging
-- **Protected Defaults** - Critical build settings are safeguarded while staying flexible
-- **Zero Config** - Works perfectly without tsconfig.json
-- **Glob Pattern Support** - Compile multiple directories with a single command
-- **Dependency-Aware** - Automatically orders compilation based on module dependencies
-- **Type Checking** - Validate code without emitting files
-- **Clean Builds** - Automatically clears output directories before compilation
-- **Auto-Unpack** - Flattens nested output directories automatically
-- **CI/CD Ready** - JSON output mode and proper exit codes
-- **Modern Defaults** - ESNext, NodeNext modules, decorators out of the box
+| Feature | Description |
+|---------|-------------|
+| 🔧 **Smart tsconfig.json Integration** | Respects all your compiler options with intelligent merging |
+| 🛡️ **Protected Defaults** | Critical build settings are safeguarded while staying flexible |
+| 🎯 **Zero Config** | Works perfectly without tsconfig.json |
+| 🌐 **Glob Pattern Support** | Compile multiple directories with a single command |
+| 📊 **Dependency-Aware** | Automatically orders compilation based on module dependencies |
+| ✅ **Type Checking** | Validate code without emitting files |
+| 🧹 **Clean Builds** | Automatically clears output directories before compilation |
+| 📁 **Auto-Unpack** | Flattens nested output directories automatically |
+| 🔄 **CI/CD Ready** | JSON output mode and proper exit codes |
+| ✨ **Modern Defaults** | ESNext, NodeNext modules, decorators out of the box |
 
-## Quick Start
+## 🚀 Quick Start
 
 ### CLI Usage
 
@@ -40,8 +46,8 @@ Compiles `./ts/**/*.ts` to `./dist_ts/`
 npx tsbuild custom src utils
 ```
 Compiles:
-- `./src/**/*.ts` to `./dist_src/`
-- `./utils/**/*.ts` to `./dist_utils/`
+- `./src/**/*.ts` → `./dist_src/`
+- `./utils/**/*.ts` → `./dist_utils/`
 
 **Auto-discover and compile in dependency order:**
 ```bash
@@ -91,7 +97,7 @@ await compiler.compileGlob({
 });
 ```
 
-## CLI Commands
+## 🛠️ CLI Commands
 
 ### 1. Default Build
 
@@ -102,12 +108,14 @@ npx tsbuild [options]
 Compiles all TypeScript files from `./ts/` to `./dist_ts/`
 
 **Options:**
-- `--skiplibcheck` - Skip type checking of declaration files
-- `--confirmskiplibcheck` - Skip lib check with extended warning (5s pause)
-- `--disallowimplicitany` - Disallow implicit `any` types
-- `--commonjs` - Use CommonJS instead of ESNext modules
-- `--json` - Output results as JSON (for CI/CD)
-- `--quiet` - Suppress console output
+| Flag | Description |
+|------|-------------|
+| `--skiplibcheck` | Skip type checking of declaration files |
+| `--confirmskiplibcheck` | Skip lib check with extended warning (5s pause) |
+| `--disallowimplicitany` | Disallow implicit `any` types |
+| `--commonjs` | Use CommonJS instead of ESNext modules |
+| `--json` | Output results as JSON (for CI/CD) |
+| `--quiet` | Suppress console output |
 
 **Examples:**
 ```bash
@@ -141,7 +149,7 @@ npx tsbuild custom src utils
 npx tsbuild custom api models services --commonjs
 ```
 
-### 3. TSFolders (Dependency-Aware)
+### 3. TSFolders (Dependency-Aware) 📊
 
 ```bash
 npx tsbuild tsfolders [options]
@@ -164,7 +172,7 @@ TypeScript Folder Compilation Plan (5 folders)
   5/5 ts_modules
 ```
 
-### 4. Emit Check
+### 4. Emit Check ✓
 
 ```bash
 npx tsbuild emitcheck <file_or_pattern> [more...] [options]
@@ -184,7 +192,7 @@ npx tsbuild emitcheck "src/**/*.ts" "test/**/*.ts"
 - `0` - All files can be emitted
 - `1` - One or more files have errors
 
-### 5. Type Check
+### 5. Type Check 🔍
 
 ```bash
 npx tsbuild check [pattern] [more...] [options]
@@ -210,7 +218,7 @@ npx tsbuild check
 # All default type checks passed!
 ```
 
-## API Reference
+## 📖 API Reference
 
 ### TsCompiler Class
 
@@ -390,7 +398,7 @@ const cli = new TsBuildCli('/path/to/project');
 cli.run();
 ```
 
-## Configuration
+## ⚙️ Configuration
 
 ### tsconfig.json Support
 
@@ -411,24 +419,28 @@ tsbuild fully supports all compiler options from `tsconfig.json`. Your project c
 }
 ```
 
-### Configuration Priority (5 Levels)
+### Configuration Priority (5 Levels) 📋
 
 When multiple configuration sources exist, they merge in this order (later overrides earlier):
 
-1. **Default Options** - tsbuild's sensible defaults
-2. **tsconfig.json** - All options from your tsconfig.json (if present)
-3. **Protected Defaults** - Critical options for build integrity
-4. **Programmatic Options** - Options passed to API functions
-5. **CLI Flags** - Command-line arguments (highest priority)
+| Priority | Source | Description |
+|----------|--------|-------------|
+| 1️⃣ | **Default Options** | tsbuild's sensible defaults |
+| 2️⃣ | **tsconfig.json** | All options from your tsconfig.json (if present) |
+| 3️⃣ | **Protected Defaults** | Critical options for build integrity |
+| 4️⃣ | **Programmatic Options** | Options passed to API functions |
+| 5️⃣ | **CLI Flags** | Command-line arguments (highest priority) |
 
-### Protected Options
+### Protected Options 🛡️
 
 These options cannot be overridden by tsconfig.json alone (but can be overridden programmatically or via CLI):
 
-- **`outDir: 'dist_ts/'`** - Required for automatic path transformations
-- **`noEmitOnError: true`** - Prevents broken builds from being emitted
-- **`declaration: true`** - Ensures `.d.ts` files for library consumers
-- **`inlineSourceMap: true`** - Consistent debugging experience
+| Option | Value | Reason |
+|--------|-------|--------|
+| `outDir` | `'dist_ts/'` | Required for automatic path transformations |
+| `noEmitOnError` | `true` | Prevents broken builds from being emitted |
+| `declaration` | `true` | Ensures `.d.ts` files for library consumers |
+| `inlineSourceMap` | `true` | Consistent debugging experience |
 
 ### Default Compiler Options
 
@@ -451,7 +463,7 @@ When no tsconfig.json exists:
 }
 ```
 
-### Path Transformation
+### Path Transformation 🔄
 
 tsbuild automatically transforms path mappings:
 
@@ -468,12 +480,12 @@ tsbuild automatically transforms path mappings:
 
 **Automatic transformation:**
 ```
-./ts_models/* -> ./dist_ts_models/*
+./ts_models/* → ./dist_ts_models/*
 ```
 
-## Features
+## ✨ Features
 
-### Clean Builds
+### Clean Builds 🧹
 
 Output directories are automatically cleared before compilation:
 
@@ -484,35 +496,129 @@ Compiling 14 files from ./ts/**/*.ts
 
 This ensures no stale files remain from previous builds.
 
-### Auto-Unpack
+### Monorepo Support with tspublish 📦
+
+tsbuild is designed to work seamlessly with [@git.zone/tspublish](https://code.foss.global/git.zone/tspublish) for monorepo workflows. This enables building and publishing multiple packages from a single repository.
+
+#### Directory Structure
+
+```
+my-project/
+├── ts/                    # Main package source
+├── ts_interfaces/         # Shared interfaces (order: 1)
+├── ts_shared/             # Shared utilities (order: 2)
+├── ts_core/               # Core logic (order: 3)
+├── ts_web/                # Web-specific code (order: 4)
+└── ts_node/               # Node-specific code (order: 5)
+```
+
+Each `ts_*` folder can contain its own `tspublish.json` to configure compilation and publishing behavior.
+
+#### tspublish.json Configuration
+
+Create a `tspublish.json` in each `ts_*` folder:
+
+```json
+{
+  "name": "@myorg/core",
+  "order": 3,
+  "unpack": true,
+  "dependencies": ["ts_interfaces", "ts_shared"]
+}
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `name` | string | — | Package name for publishing |
+| `order` | number | `Infinity` | Build sequence (lower builds first) |
+| `unpack` | boolean | `true` | Flatten nested output directories |
+| `dependencies` | string[] | — | Monorepo dependencies to bundle |
+
+#### Build Order
+
+The `tsfolders` command respects the `order` property:
+
+```bash
+npx tsbuild tsfolders
+```
+
+**Default ordering (without tspublish.json):**
+1. `ts_interfaces` - always first (shared types)
+2. `ts_shared` - always second (shared utilities)
+3. Other folders sorted by `order` property
+4. Folders without `order` are built last
+
+**Example output:**
+```
+TypeScript Folder Compilation Plan (5 folders)
+  1/5 ts_interfaces  (order: 1)
+  2/5 ts_shared      (order: 2)
+  3/5 ts_core        (order: 3)
+  4/5 ts_web         (order: 4)
+  5/5 ts_node        (order: 5)
+```
+
+### Auto-Unpack 📁
 
 When TypeScript compiles files that import from sibling directories, it creates nested output:
 
 ```
 dist_ts_core/
-  ts_core/        <- nested output
-  ts_shared/      <- pulled-in dependency
+  ts_core/        ← nested output
+  ts_shared/      ← pulled-in dependency
 ```
 
 tsbuild automatically flattens this to:
 
 ```
 dist_ts_core/
-  index.js        <- flat
+  index.js        ← flat, clean structure
 ```
 
-Configure via `tspublish.json` in source folder:
+This is especially important for monorepos where packages import from each other.
+
+**Control via tspublish.json:**
 ```json
 {
   "unpack": true
 }
 ```
 
-Set `"unpack": false` to disable.
+- `"unpack": true` (default) - Flatten nested directories after compilation
+- `"unpack": false` - Keep original nested structure
 
-### Decorator Support
+**What gets unpacked:**
+- The source folder's contents (`ts_core/`) are moved to the root of `dist_ts_core/`
+- Sibling folders (`ts_shared/`) that were pulled in are removed (they have their own dist)
 
-First-class decorator support out of the box:
+### Decorator Support 🎨
+
+tsbuild supports both **TC39 standard decorators** (recommended) and legacy experimental decorators.
+
+**TC39 Standard Decorators (Preferred)** 🌟
+
+We strongly recommend using TC39 standard decorators for all new code. They are the official JavaScript standard and provide better semantics:
+
+```typescript
+// TC39 standard decorator
+function log(target: any, context: ClassMethodDecoratorContext) {
+  return function (...args: any[]) {
+    console.log(`Calling ${String(context.name)}`);
+    return target.apply(this, args);
+  };
+}
+
+class UserService {
+  @log
+  getUser(id: string) {
+    return { id, name: 'John' };
+  }
+}
+```
+
+**Legacy Decorators (Backwards Compatibility)**
+
+For existing projects using frameworks like NestJS, TypeORM, or Angular that still require experimental decorators:
 
 ```typescript
 @Injectable()
@@ -524,9 +630,19 @@ class UserService {
 }
 ```
 
-Works with NestJS, TypeORM, Inversify, Angular, and other DI frameworks.
+Enable legacy decorators in your `tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
 
-## CI/CD Integration
+> 💡 **Tip:** When starting new projects or migrating existing ones, prefer TC39 decorators. They're the future of JavaScript and don't require experimental flags.
+
+## 🔄 CI/CD Integration
 
 ### GitHub Actions
 
@@ -578,7 +694,7 @@ npx tsbuild --json --quiet
 }
 ```
 
-## Troubleshooting
+## 🔧 Troubleshooting
 
 ### Common Issues
 
@@ -607,27 +723,23 @@ npx tsbuild --skiplibcheck
 
 Only use this if you trust your dependencies' type definitions.
 
-## Issue Reporting
-
-For reporting issues or vulnerabilities, please visit our community at [community.foss.global](https://community.foss.global). We're looking forward to your contribution!
-
-For repository access: [code.foss.global/git.zone/tsbuild](https://code.foss.global/git.zone/tsbuild)
-
 ## License and Legal Information
 
-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.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
 
 **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.
 
 ### Trademarks
 
-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.
+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 or third parties, 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 or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
 
 ### Company Information
 
 Task Venture Capital GmbH
 Registered at District Court Bremen HRB 35230 HB, Germany
 
-For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
 
 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.

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/tsbuild',
-  version: '4.0.2',
+  version: '4.1.0',
   description: 'A tool for compiling TypeScript files using the latest nightly features, offering flexible APIs and a CLI for streamlined development.'
 }