# Kandev Launcher (npx)

## Architecture

```mermaid
flowchart TD
    A["npx kandev"] --> B["npm downloads kandev package"]
    B --> C["CLI parses arguments"]
    C --> D{"Command?"}

    D -->|run| E["Fetch latest GitHub release"]
    D -->|dev| F["Use local repo"]
    D -->|start| G["Use local build"]

    E --> E1["Download platform zip"]
    E1 --> E2["Extract to ~/.kandev/bin/"]
    E2 --> E3["Start backend + Next.js standalone"]

    F --> F1["make dev + next dev"]

    G --> G1["binary + next start"]
```

## Overview

This package powers `npx kandev` by downloading prebuilt release bundles from GitHub Releases and running them locally. It:

- Detects OS/arch and fetches the matching bundle ZIP.
- Verifies the SHA256 checksum when available.
- Extracts the bundle into `~/.kandev/bin/<version>/<platform>/`.
- Starts the backend binary and waits for the `/health` endpoint.
- Starts the Next.js standalone server with runtime `KANDEV_API_BASE_URL`.
- Uses the latest GitHub Release by default, so runtime bundles update automatically.

It also supports local dev and production runs from a repo checkout.

## Commands

| Command                  | Description                                              |
| ------------------------ | -------------------------------------------------------- |
| `kandev` or `kandev run` | Download and run release bundles (default)               |
| `kandev dev`             | Run local repo with hot-reload (requires repo checkout)  |
| `kandev start`           | Run local production build (requires `make build` first) |

## Updates

On `run`, the launcher checks npm for the latest `kandev` CLI version and prompts:

```
Update available: <current> -> <latest>. Update now? [y/N]
```

If you accept, it re-runs `npx kandev@latest` with the same arguments.
This check is skipped in `dev` and `start` modes.

Note: the runtime bundles are pulled from the latest GitHub Release by default, even if the CLI version is unchanged. So:

- **New runtime release without CLI publish**: users get new runtime automatically, but no update prompt.
- **New CLI publish**: users get an update prompt and then re-run with the new CLI.
- On startup, `run` also prints the resolved runtime release tag.
- Runtime assets are published atomically in CI (single final release upload job), so `/releases/latest`
  does not surface partially uploaded platform bundles.

You can disable the prompt with:

```bash
KANDEV_NO_UPDATE_PROMPT=1 npx kandev
```

## Usage

```bash
# Run the latest release bundle
npx kandev

# Run a specific release tag
npx kandev run --version v0.1.0

# Override ports
npx kandev --backend-port 18080 --web-port 13000

# Local dev with hot-reload (from repo)
npx kandev dev

# Local production build (from repo, after `make build`)
npx kandev start

# Local test the built CLI (from repo root)
pnpm -C apps/cli build
pnpm -C apps/cli start
```

## CLI Options

| Option                  | Description                              |
| ----------------------- | ---------------------------------------- |
| `run`                   | Use release bundles (default)            |
| `dev`                   | Use local repo with hot-reload           |
| `start`                 | Use local production build               |
| `--version <tag>`       | Release tag to install (default: latest) |
| `--backend-port <port>` | Override backend port                    |
| `--web-port <port>`     | Override web port                        |
| `--help`, `-h`          | Show help                                |

## Local Development

```bash
# Run CLI in dev mode
pnpm -C apps/cli dev

# Run with arguments
pnpm -C apps/cli dev -- start
pnpm -C apps/cli dev -- --backend-port 9000
```

## Build / Publish

```bash
pnpm -C apps/cli build
npm publish --access public
```

The published package name is `kandev`, with a bin entry `kandev`.

## Release

```bash
scripts/release/release.sh
```

The unified release script supports `cli`, `app`, or `both` in one flow.
Versioning strategy:

- App release tags: `vM.m`
- CLI npm version: `M.m.0`
- Default bump mode: `minor`

## Environment Overrides

| Variable                    | Description                                    |
| --------------------------- | ---------------------------------------------- |
| `KANDEV_GITHUB_OWNER`       | Override GitHub repo owner (default: `kandev`) |
| `KANDEV_GITHUB_REPO`        | Override GitHub repo name (default: `kandev`)  |
| `KANDEV_GITHUB_TOKEN`       | Optional token for GitHub API rate limits      |
| `KANDEV_NO_UPDATE_PROMPT=1` | Disable the CLI update prompt                  |
| `KANDEV_SKIP_UPDATE=1`      | Internal guard to avoid update loops           |
| `KANDEV_HEALTH_TIMEOUT_MS`  | Override health check timeout in milliseconds  |

## Supported Platforms

| Platform              | Asset Name                                  |
| --------------------- | ------------------------------------------- |
| macOS (Apple Silicon) | `kandev-macos-arm64.zip`                    |
| macOS (Intel)         | `kandev-macos-x64.zip`                      |
| Linux (x64)           | `kandev-linux-x64.zip`                      |
| Linux (ARM64)         | `kandev-linux-arm64.zip`                    |
| Windows (x64)         | `kandev-windows-x64.zip`                    |
| Windows (ARM64)       | Falls back to `windows-x64` (x64 emulation) |