marco-trest-test/docs/trest-onboarding.md

# TREST Onboarding Guide (Private Repo)

This guide is designed for a new joiner to quickly set up access, install, and understand usage of the private `trest` package hosted at:

- https://gitea.jig.com.hk/jig-software/trest

Because the repository is private, this guide uses a secure workflow that works in most teams.

## 1) Access Prerequisites

Make sure you have:

- A working company VPN connection (if required by network policy).
- A Gitea account with access to `jig-software/trest`.
- A Personal Access Token (PAT) in Gitea with at least repository read scope.
- Git installed locally.

Quick checks:

```bash
git --version
ssh -T git@gitea.jig.com.hk
```

If SSH is not configured yet, follow section 2.

## 2) Set Up Git Access

Choose one method.

### Option A: SSH (recommended)

1. Generate a key if you do not already have one:

```bash
ssh-keygen -t ed25519 -C "your.name@company.com"
```

2. Start agent and add key:

```bash
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
```

3. Copy and add your public key to Gitea:

```bash
cat ~/.ssh/id_ed25519.pub
```

4. Test auth:

```bash
ssh -T git@gitea.jig.com.hk
```

### Option B: HTTPS + PAT

Use HTTPS clone and enter your username + PAT when prompted.

```bash
git clone https://gitea.jig.com.hk/jig-software/trest.git
```

## 3) Clone and Inspect the Repository

```bash
git clone git@gitea.jig.com.hk:jig-software/trest.git
cd trest
```

Collect quick project facts:

```bash
ls -la
find . -maxdepth 2 -type f | head -50
```

Identify the ecosystem from marker files:

- `package.json` -> Node.js package
- `pyproject.toml` or `setup.py` -> Python package
- `Cargo.toml` -> Rust crate
- `go.mod` -> Go module

## 4) Install Runtime and Dependencies

Use the matching path below.

### If `trest` is Node.js

If your team distributes `trest` through Gitea Packages (npm registry), configure Yarn auth first.

If Yarn is new to you, read `docs/yarn-basics-cheatsheet.md` first.

#### Yarn 4 + Gitea Registry Setup

This workspace already uses a scoped registry in `.yarnrc.yml`.

Required scope assumptions:

- Scope: `@jig-software`
- Registry URL: `https://gitea.jig.com.hk/api/packages/jig-software/npm/`

Set your token in the current shell:

```bash
export JIG_SOFTWARE_GITEA_DEPLOYMENT_TOKEN="<your-gitea-token>"
```

Verify package access (recommended):

```bash
yarn npm info @jig-software/trest
```

Optional identity check (only if your Gitea npm endpoint supports whoami):

```bash
yarn npm whoami --scope jig-software
```

If package info is returned, install `trest`:

```bash
yarn add @jig-software/trest
```

If package naming differs, discover the exact name from your team or the Gitea Packages page, then run `yarn add <exact-package-name>`.

#### Fallback: Install Directly From Gitea Git

Use this when `trest` exists as a private repository but is not published in Gitea Packages npm.

SSH form:

```bash
yarn add trest@git+ssh://git@gitea.jig.com.hk/jig-software/trest.git
```

HTTPS form:

```bash
yarn add trest@git+https://gitea.jig.com.hk/jig-software/trest.git
```

Pin to a branch, tag, or commit for reproducibility:

```bash
yarn add trest@git+ssh://git@gitea.jig.com.hk/jig-software/trest.git#main
```

```bash
node -v
npm -v
npm ci
npm test
```

Yarn note:

- This repo uses Plug'n'Play (`nodeLinker: pnp`). If a tool expects `node_modules`, you can switch linker mode for that project.

### If `trest` is Python

```bash
python3 --version
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt
pytest -q
```

### If `trest` is Rust

```bash
rustc --version
cargo --version
cargo test
```

### If `trest` is Go

```bash
go version
go test ./...
```

## 5) Understand Package Usage Quickly

Work top-down with this sequence:

1. Read `README.md` and `docs/` first.
2. Find entry points:
   - Node: `main`, `exports`, `src/index.*`
   - Python: package `__init__.py`, public modules
   - Rust: `src/lib.rs`, `src/main.rs`
   - Go: exported symbols in key package files
3. Locate examples/tests to learn intended behavior.
4. Build a tiny local consumer project and call the simplest public API.

Search commands:

```bash
rg "example|usage|quick start|getting started|test" -n .
rg "export|public|def |class |func " -n src tests .
```

## 6) Create a Minimal Consumer Sandbox

In a separate directory, create a tiny app that imports `trest` and performs one happy-path call.

Suggested structure:

```text
sandbox/
  README.md
  <language standard files>
  smoke_test.*
```

Your first smoke test should validate:

- Package can be installed or linked.
- Import works.
- One primary API call returns expected output.
- Error handling behavior for invalid input is understood.

## 7) Team Questions to Ask Early

Ask these within your first day to avoid drift:

- Which branch/tag/version should new projects consume?
- Is there a compatibility matrix (runtime versions, OS, architecture)?
- What APIs are stable vs experimental?
- Any required env vars, secrets, or service dependencies?
- Preferred testing strategy for downstream consumers?

## 8) Troubleshooting

- `404`/auth failures: confirm VPN, permissions, token scope, and clone URL.
- SSL/cert issues: check corporate certificate installation and git SSL settings.
- Install failures: pin runtime version from project config files (`.nvmrc`, `pyproject`, etc.).
- Test failures: run a single test first, then expand scope.

## 9) Onboarding Completion Checklist

You are done when all are true:

- [ ] Can clone `jig-software/trest` locally.
- [ ] Can install dependencies successfully.
- [ ] Can run test suite (or at least smoke tests).
- [ ] Can explain top 3 public APIs in your own words.
- [ ] Have written notes on setup steps and pitfalls for the team.