szci/readme.md

# @ship.zone/szci

**Serve Zone CI** - A powerful CI/CD tool for streamlining Node.js and Docker workflows within CI environments (GitLab CI, GitHub CI, Gitea CI). Now powered by Deno with standalone executables.

## ✨ Features

- 🚀 **Standalone Executables** - No Node.js installation required
- 🐳 **Docker Integration** - Build, tag, and push Docker images
- 📦 **NPM Management** - Install, test, and publish npm packages
- 🔧 **Node.js Version Management** - Install and switch between Node versions
- 🔐 **SSH Key Management** - Deploy SSH keys from environment variables
- ☁️ **Multi-Registry Support** - Push to multiple Docker registries
- 🎯 **Cross-Platform** - Binaries for Linux, macOS, and Windows

## 📥 Installation

### NPM (Recommended)

```sh
npm install -g @ship.zone/szci
```

The package will automatically download the appropriate pre-compiled binary for your platform.

### From Source (Deno Required)

```sh
git clone https://code.foss.global/ship.zone/szci.git
cd szci
deno task compile
```

## 🚀 Quick Start

```sh
# Install Node.js
szci node install stable

# Install dependencies
szci npm install

# Build Docker images
szci docker build

# Run tests
szci npm test

# Push Docker images
szci docker push registry.example.com
```

## 📖 Usage

### Node.js Management

```sh
# Install specific Node.js version
szci node install lts
szci node install stable
szci node install 18

# Install from .nvmrc
szci node install legacy
```

### NPM Commands

```sh
# Install dependencies
szci npm install

# Run tests
szci npm test

# Publish package
szci npm publish
```

### Docker Workflows

```sh
# Prepare Docker environment
szci docker prepare

# Build all Dockerfiles
szci docker build

# Push to registry
szci docker push registry.example.com

# Pull from registry
szci docker pull registry.example.com

# Test Dockerfiles
szci docker test
```

### SSH Key Management

```sh
# Deploy SSH keys from environment
szci ssh prepare
```

Set environment variables like `NPMCI_SSHKEY_1`, `NPMCI_SSHKEY_2`, etc.

## 🔧 CI/CD Integration

### GitLab CI

```yaml
image: denoland/deno:alpine

stages:
  - prepare
  - build
  - test
  - deploy

variables:
  SZCI_VERSION: "latest"

before_script:
  - deno install --allow-all --global --name szci https://code.foss.global/ship.zone/szci/raw/branch/master/mod.ts
  # OR use the npm package:
  # - npm install -g @ship.zone/szci

prepare:
  stage: prepare
  script:
    - szci node install stable
    - szci npm install

build:
  stage: build
  script:
    - szci docker build

test:
  stage: test
  script:
    - szci npm test

deploy:
  stage: deploy
  script:
    - szci docker push $CI_REGISTRY
  only:
    - master
```

### GitHub Actions

```yaml
name: CI Pipeline

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Install SZCI
        run: npm install -g @ship.zone/szci

      - name: Setup Node.js
        run: szci node install stable

      - name: Install Dependencies
        run: szci npm install

      - name: Build Docker Images
        run: szci docker build

      - name: Run Tests
        run: szci npm test

      - name: Push Images
        if: github.ref == 'refs/heads/main'
        run: szci docker push ghcr.io
```

## ⚙️ Configuration

Create an `npmextra.json` file in your project root:

```json
{
  "npmci": {
    "npmGlobalTools": [],
    "npmAccessLevel": "public",
    "npmRegistryUrl": "registry.npmjs.org",
    "dockerRegistries": [
      "registry.gitlab.com"
    ],
    "dockerRegistryRepoMap": {
      "registry.gitlab.com": "mygroup/myrepo"
    },
    "dockerBuildargEnvMap": {
      "ARG_NAME": "ENV_VAR_NAME"
    }
  }
}
```

## 🐳 Docker Registry Authentication

SZCI supports automatic authentication with:

- GitLab CI Registry (via `CI_JOB_TOKEN`)
- Custom registries via environment variables

Set `NPMCI_LOGIN_DOCKER*` environment variables:

```sh
NPMCI_LOGIN_DOCKER_1="registry.example.com|username|password"
NPMCI_LOGIN_DOCKER_2="another-registry.com|user2|pass2"
```

## 🏗️ Development

### Prerequisites

- Deno 1.40+ installed

### Building from Source

```sh
# Clone the repository
git clone https://code.foss.global/ship.zone/szci.git
cd szci

# Compile for all platforms
deno task compile

# Compile for current platform only
deno compile --allow-all --output szci mod.ts

# Run tests
deno task test

# Development mode
deno task dev --help
```

### Testing

SZCI uses Deno's native test framework:

```sh
# Run all tests
deno task test

# Run tests in watch mode
deno task test:watch

# Run specific test file
deno test --allow-all test/test.cloudly.ts
```

## 📦 Binary Sizes

The standalone executables are approximately:
- Linux x64: ~800MB
- Linux ARM64: ~800MB
- macOS x64: ~796MB
- macOS ARM64: ~796MB
- Windows x64: ~804MB

Sizes include all dependencies and the Deno runtime.

## 🔄 Migration from npmci

If you're upgrading from the old `@ship.zone/npmci` package:

1. Update package references:
   ```sh
   npm uninstall -g @ship.zone/npmci
   npm install -g @ship.zone/szci
   ```

2. Update CI configuration files - replace `npmci` with `szci`

3. The command interface remains the same, only the binary name changed

## 📝 License

MIT © Lossless GmbH

## 🔗 Links

- [Repository](https://code.foss.global/ship.zone/szci)
- [Issues](https://code.foss.global/ship.zone/szci/issues)
- [Changelog](./changelog.md)

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

**Built with Deno 🦕**