Metadata-Version: 2.4
Name: tooig
Version: 0.1.3
Summary: Interactive framework for tooig developer program
Project-URL: Documentation, https://developer.tooig.com/get_started
Project-URL: Issues, https://github.com/tooig/developer/issues
Project-URL: Repository, https://github.com/tooig/developer
Author-email: "Tooig, Inc" <tooighq@gmail.com>
License: MIT
Keywords: cli,developer,nineth,tooig
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: platformdirs<5,>=4.2
Requires-Dist: questionary<3,>=2.1
Requires-Dist: rich<15,>=13.9
Requires-Dist: typer<1,>=0.15
Description-Content-Type: text/markdown

# tooig CLI

`tooig` is the secure setup CLI for Tooig developers. It is published with the same name and version to PyPI and npm. Both distributions implement the same authentication, build authorization, credential-storage, and SDK-installation flow.

## Table of contents

1. [Requirements](#requirements)
2. [Installation](#installation)
3. [Developer setup walkthrough](#developer-setup-walkthrough)
4. [Authentication](#authentication)
5. [Build authorization](#build-authorization)
6. [Framework installation](#framework-installation)
7. [Credential storage](#credential-storage)
8. [Configuration](#configuration)
9. [Service contract](#service-contract)
10. [Security model](#security-model)
11. [Troubleshooting](#troubleshooting)
12. [Release process](#release-process)

## Requirements

Use either of these runtimes:

- Python 3.10 or newer and `pip`.
- Node.js 20 or newer and npm or pnpm.

The selected framework must exist in the same package registry as the installed CLI. The Python CLI installs from PyPI; the Node.js CLI installs from npm.

## Installation

### Python and pip

```console
python -m pip install --upgrade tooig
tooig developer
```

### npm

Install globally:

```console
npm install --global tooig
tooig developer
```

Or run without a permanent global installation:

```console
npx tooig developer
```

### pnpm

```console
pnpm add --global tooig
tooig developer
```

Or:

```console
pnpm dlx tooig developer
```

`npx install --g tooig` is not a valid npm installation command. Use `npm install --global tooig` or `npx tooig developer` instead.

## Developer setup walkthrough

Run:

```console
tooig developer
```

The CLI performs these steps:

1. Prompts for the name portion of the developer email. Enter `ada` for `ada@developer.tooig.com`.
2. Offers **Sign in** and **Create developer account**.
3. Reads the password without echoing characters to the terminal.
4. Authenticates with the Tooig API.
5. Offers browser authorization or an existing API key.
6. Validates and stores the resulting API key.
7. Offers `nineth` and `bridge (nineth-bridge)`.
8. Installs the selected SDK using the CLI's package ecosystem.
9. Prints the getting-started URL: <https://developer.tooig.com/get_started>.

Use `--no-open` on remote machines to print the browser authorization URL without launching a browser:

```console
tooig developer --no-open
```

## Authentication

The prompt accepts only the local portion of a Tooig developer address:

```text
email: [name]@developer.tooig.com
```

The suffix is fixed by the CLI. Local parts are normalized to lowercase and may contain letters, numbers, dots, underscores, and hyphens.

For a new account, select **Create developer account** and use a password of at least 12 characters. The CLI submits the signup and then authenticates. If the account policy requires email verification, verify the address and run `tooig developer` again.

Passwords and short-lived login tokens are held in memory only. They are never written to the credential file or displayed in progress/error output.

## Build authorization

### Secure browser link

The CLI asks the Tooig API to create a signed, short-lived authorization request. The service returns the link; the CLI does not generate or sign authorization links locally.

```text
https://developer.tooig.com/{server-generated-id}
```

The link is opened in the default browser unless `--no-open` is set. The CLI polls the service until the request is approved, denied, cancelled, or expired. On approval, the service returns the build API key.

The CLI rejects an authorization URL that changes the configured API host or downgrades HTTPS. Localhost development may use HTTP.

### Existing API key

Select **Use an existing API key**. Input is hidden. Before storing the key, the CLI validates it against the authenticated session endpoint. Invalid or truncated keys are not saved.

## Framework installation

The framework choices and commands are:

| CLI distribution | Selection | Command |
| --- | --- | --- |
| PyPI | `nineth` | `python -m pip install --upgrade nineth` |
| PyPI | `bridge` | `python -m pip install --upgrade nineth-bridge` |
| npm | `nineth` | `npm install nineth` |
| npm | `bridge` | `npm install nineth-bridge` |
| pnpm | `nineth` | `pnpm add nineth` |
| pnpm | `bridge` | `pnpm add nineth-bridge` |

The Node.js CLI detects pnpm through `npm_config_user_agent`; all other npm/npx invocations use npm. Installer commands use argument arrays and never interpolate user input into a shell command.

## Credential storage

Python and Node.js use the same versioned JSON format so either CLI can reuse the authorization:

| Platform | Default location |
| --- | --- |
| Windows | `%APPDATA%\\tooig\\credentials.json` |
| macOS | `~/Library/Application Support/tooig/credentials.json` |
| Linux | `${XDG_CONFIG_HOME:-~/.config}/tooig/credentials.json` |

The file contains the developer email, API base URL, and API key. It never contains the password or login token.

Writes use a temporary file followed by an atomic rename. On POSIX systems the directory is mode `0700` and the file is mode `0600`. Both clients refuse to read or replace a symlinked credential file. Do not commit this file or copy it into a project directory.

## Configuration

The production API is used by default:

```text
https://developer.tooig.com/api
```

Override it for development with `TOOIG_API_URL` or `--api-url`:

```console
tooig developer --api-url http://localhost:8000/api
```

Non-local API URLs must use HTTPS and cannot contain embedded usernames or passwords.

## Service contract

The CLI expects these server endpoints relative to the API base URL:

| Method | Endpoint | Purpose |
| --- | --- | --- |
| `POST` | `/auth/signup` | Create a developer account. |
| `POST` | `/auth/login` | Return a short-lived `access_token`. |
| `GET` | `/auth/session` | Validate an existing bearer API key. |
| `POST` | `/developer/authorizations` | Create a signed browser authorization request. |
| `GET` | `/developer/authorizations/{id}` | Poll `pending`, `approved`, `denied`, `cancelled`, or `expired`. |

The authorization creation response is:

```json
{
  "id": "server-generated-id",
  "authorization_url": "https://developer.tooig.com/server-generated-id",
  "interval": 2,
  "expires_in": 300
}
```

An approved poll response is:

```json
{
  "status": "approved",
  "api_key": "server-issued-secret"
}
```

The repository currently supplies `/auth/signup`, `/auth/login`, and `/auth/session`. Browser authorization requires the `/developer/authorizations` service to be deployed before that option can complete. Existing API-key authorization is usable against the current API.

## Security model

- HTTPS is mandatory except for loopback development.
- Password and API-key prompts do not echo input.
- The server signs and issues authorization requests and keys.
- Authorization URLs are origin-checked before opening.
- Login tokens are not persisted.
- Existing keys are validated before persistence.
- Secrets are not passed as command-line arguments to package managers.
- Network failures are converted to bounded errors without response dumps.
- Framework names are selected from a fixed allowlist.
- Credential writes are atomic and symlink-resistant.

Local credential-file protection is not a substitute for full-disk encryption or a locked operating-system account. Rotate the API key immediately if the workstation or file is compromised.

## Troubleshooting

### Account creation succeeds but login fails

The account may require email verification. Complete verification and rerun `tooig developer` using **Sign in**.

### Browser authorization is unavailable

Use **Use an existing API key** until the browser-authorization service is deployed. For remote or headless environments, use `--no-open` and open the printed link on another trusted device.

### Package installation fails

Check registry access and install the selected package directly using the command in [Framework installation](#framework-installation). The authorization remains stored, so rerunning setup does not expose the password or key.

### PowerShell blocks `npm.ps1`

Use `npm.cmd` in a restricted PowerShell session or adjust the local execution policy according to your organization's policy. The published `tooig` executable itself does not require shell interpolation.

## Release process

Repository versioning is controlled by the first recognized dispatch token in a commit message:

| Dispatch | Version bump | Repository | PyPI/npm `tooig` |
| --- | --- | --- | --- |
| `build:` | Major | Bump and GitHub release | No publish |
| `feat:` | Minor | Bump and GitHub release | No publish |
| `chore:` | Patch | Bump and GitHub release | No publish |
| `build[tooig]:` | Major | Bump and GitHub release | Bump, build, validate, publish, release |
| `feat[tooig]:` | Minor | Bump and GitHub release | Bump, build, validate, publish, release |
| `chore[tooig]:` | Patch | Bump and GitHub release | Bump, build, validate, publish, release |

The PyPI and npm versions must match before a scoped release. The script updates both manifests and the npm lockfile together. Repository tags use `vX.Y.Z`; package tags use `tooig-vX.Y.Z`.

GitHub Actions requires:

- An npm automation token in the `NPM_TOKEN` repository secret.
- PyPI Trusted Publishing configured for this repository and workflow.
- `contents: write` and `id-token: write`, already declared by the workflow.

The repository release reads `.github/release_notes/repository.md`. The package release reads `.github/release_notes/tooig.md`.
