fix(packaging): Rename package scope to @git.zone and migrate deps/CI; pin pnpm and enable ESM packaging

This commit is contained in:
2025-12-13 09:44:37 +00:00
parent c31df766fc
commit c538e6b10b
14 changed files with 389 additions and 28099 deletions

View File

@@ -1,4 +1,4 @@
# @gitzone/tsdocker
# @git.zone/tsdocker
> 🐳 Cross-platform npm module development with Docker — test your packages in clean, reproducible Linux environments every time.
@@ -18,18 +18,21 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
## Features
**Works Everywhere Docker Does**
- Docker Toolbox
- Native Docker Desktop
- Docker-in-Docker (DinD)
- Mounted docker.sock scenarios
🔧 **Flexible Configuration**
- Custom base images
- Configurable test commands
- Environment variable injection via qenv
- Optional docker.sock mounting for nested container tests
📦 **TypeScript-First**
- Full TypeScript support with excellent IntelliSense
- Type-safe configuration
- Modern async/await patterns throughout
@@ -37,9 +40,9 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
## Installation
```bash
npm install --save-dev @gitzone/tsdocker
npm install --save-dev @git.zone/tsdocker
# or
pnpm install --save-dev @gitzone/tsdocker
pnpm install --save-dev @git.zone/tsdocker
```
## Quick Start
@@ -65,6 +68,7 @@ npx tsdocker
```
That's it! tsdocker will:
1. ✅ Verify Docker is available
2. 🏗️ Build a test container with your specified base image
3. 📂 Mount your project directory
@@ -73,10 +77,10 @@ That's it! tsdocker will:
## Configuration Options
| Option | Type | Description |
|--------|------|-------------|
| `baseImage` | `string` | Docker image to use as the test environment base |
| `command` | `string` | CLI command to execute inside the container |
| Option | Type | Description |
| ------------ | --------- | ---------------------------------------------------------------------- |
| `baseImage` | `string` | Docker image to use as the test environment base |
| `command` | `string` | CLI command to execute inside the container |
| `dockerSock` | `boolean` | Whether to mount `/var/run/docker.sock` for Docker-in-Docker scenarios |
### Environment Variables
@@ -84,6 +88,7 @@ That's it! tsdocker will:
If you have a `qenv.yml` file in your project, tsdocker automatically loads and injects those environment variables into your test container.
Example `qenv.yml`:
```yaml
demoKey: demoValue
API_KEY: your-key-here
@@ -92,16 +97,21 @@ API_KEY: your-key-here
## CLI Commands
### Standard Test Run
```bash
tsdocker
```
Runs your configured test command in a fresh Docker container.
### Clean Docker Environment
```bash
tsdocker clean --all
```
⚠️ **WARNING**: This aggressively cleans your Docker environment by:
- Killing all running containers
- Removing all stopped containers
- Removing dangling images
@@ -111,15 +121,19 @@ tsdocker clean --all
Use with caution!
### VSCode in Docker
```bash
tsdocker vscode
```
Launches a containerized VS Code instance accessible via browser at `testing-vscode.git.zone:8443`.
### Speed Test
```bash
tsdocker speedtest
```
Runs a network speed test inside a Docker container.
## Advanced Usage
@@ -154,6 +168,7 @@ You can use any Docker image as your base:
```
Popular choices:
- `node:20` — Official Node.js images
- `node:20-alpine` — Lightweight Alpine-based images
- `hosttoday/ht-docker-node:npmts` — Pre-configured with npmts tooling
@@ -161,6 +176,7 @@ Popular choices:
### CI Integration
tsdocker automatically detects CI environments (via `CI=true` env var) and adjusts behavior:
- Skips mounting project directory in CI (assumes code is already in container)
- Optimizes for CI execution patterns
@@ -169,6 +185,7 @@ tsdocker automatically detects CI environments (via `CI=true` env var) and adjus
### The Problem
Local development environments drift over time. You might have:
- Stale global packages
- Modified system configurations
- Cached dependencies
@@ -190,15 +207,15 @@ tsdocker ensures every test run happens in a **clean, reproducible environment**
tsdocker is built with TypeScript and provides full type definitions:
```typescript
import { IConfig } from '@gitzone/tsdocker/dist/tsdocker.config';
import { IConfig } from '@git.zone/tsdocker/dist/tsdocker.config';
const config: IConfig = {
baseImage: 'node:20',
command: 'npm test',
dockerSock: false,
keyValueObject: {
NODE_ENV: 'test'
}
NODE_ENV: 'test',
},
};
```
@@ -234,6 +251,7 @@ docker --version
### Tests fail in container but work locally
This often indicates environment-specific issues. Check:
- Are all dependencies in `package.json`? (not relying on global packages)
- Does your code have hardcoded paths?
- Are environment variables set correctly?
@@ -250,6 +268,7 @@ sudo usermod -aG docker $USER
## Examples
### Basic npm test
```json
{
"npmdocker": {
@@ -260,6 +279,7 @@ sudo usermod -aG docker $USER
```
### Using npmci for multiple Node versions
```json
{
"npmdocker": {
@@ -270,6 +290,7 @@ sudo usermod -aG docker $USER
```
### Testing Docker-based tools
```json
{
"npmdocker": {
@@ -286,9 +307,9 @@ sudo usermod -aG docker $USER
🚀 **Layer caching**: Docker caches image layers — your base image only downloads once
🚀 **Prune regularly**: Run `docker system prune` periodically to reclaim disk space
## Migration from @gitzone/npmdocker
## Migration from legacy npmdocker scope
This package was previously published as `@gitzone/npmdocker`. The scope has been updated to `@gitzone/tsdocker` for better naming consistency. Functionality remains the same.
This package was previously published under the `npmdocker` name in the old scope. It is now available as `@git.zone/tsdocker` for better naming consistency. Functionality remains the same.
## License and Legal Information