docs: brew install, runtime resolution, and GHA-driven release flow
- README.md: add Homebrew quick start (brew install kdlbs/kandev/kandev), update NPX docs to require npm 7+, document the three update paths. - docs/cli.md: rewrite architecture diagram to show three-step runtime resolution. Replace --version <tag> docs with --version (CLI semver) + --runtime-version <tag> (advanced/debug). Remove KANDEV_NO_UPDATE_PROMPT. - apps/cli/README.md: add Homebrew install path; document package-manager-owned updates. - apps/cli/README_internal.md: rewrite to describe the npm package vs GitHub bundle artifact-shape distinction and the three-step resolver. Document the GHA-driven release UI (Run workflow + bump dropdown). - AGENTS.md: add Release & Versioning Convention section describing the unified single-SemVer flow, the sibling channel model, and the GHA flow.
This commit is contained in:
@@ -274,6 +274,36 @@ lib/api/domains/ # API clients
|
||||
|
||||
Commits to `main` **must** follow [Conventional Commits](https://www.conventionalcommits.org/) (`type: description`). PRs are squash-merged — the PR title becomes the commit, validated by CI. Changelog is auto-generated from these via git-cliff (`cliff.toml`). See `.agents/skills/commit/SKILL.md` for allowed types and examples.
|
||||
|
||||
### Release & Versioning Convention
|
||||
|
||||
Kandev uses a **single SemVer** `X.Y.Z` shared across all distribution channels:
|
||||
|
||||
- `apps/cli/package.json` version → `X.Y.Z`
|
||||
- npm main package: `kandev@X.Y.Z`
|
||||
- npm runtime packages: `@kdlbs/runtime-{platform}@X.Y.Z` (5 platforms; declared as `optionalDependencies` in main package)
|
||||
- Git tag: `vX.Y.Z` (three-part; legacy `vM.m` tags normalize to `M.m.0`)
|
||||
- Homebrew formula: `kdlbs/homebrew-kandev` `Formula/kandev.rb` `version "X.Y.Z"`
|
||||
- GitHub release: `vX.Y.Z` with platform tarballs `kandev-{platform}.tar.gz` + `.sha256`
|
||||
|
||||
**npm and Homebrew are sibling channels**, not chained. Both consume the same GitHub release artifacts; neither depends on the other.
|
||||
|
||||
**Release flow** (entirely in CI via `.github/workflows/release.yml`, triggered by maintainer from GitHub Actions UI):
|
||||
|
||||
1. Maintainer clicks "Run workflow" → picks `bump` (patch/minor/major) → optional `dry_run`.
|
||||
2. `prepare` job bumps version + regenerates CHANGELOG, opens release PR, squash-merges, tags `vX.Y.Z`.
|
||||
3. `build-web` + `build-cli` + `build-bundles` (5 platforms) build the release artifacts.
|
||||
4. `publish-release` creates the GitHub release with platform tarballs + sha256 + auto-generated notes.
|
||||
5. `publish-npm` publishes 5 `@kdlbs/runtime-*` packages + main `kandev` package to npmjs.
|
||||
6. `update-homebrew-tap` pushes updated `Formula/kandev.rb` to `kdlbs/homebrew-kandev` via SSH deploy key.
|
||||
|
||||
There is no local release script — the entire flow runs in GHA.
|
||||
|
||||
**Runtime resolution** (in `apps/cli/src/runtime.ts`):
|
||||
|
||||
1. `KANDEV_BUNDLE_DIR` env var (set by Homebrew wrapper, used by tests).
|
||||
2. Installed `@kdlbs/runtime-{platform}` npm package via `require.resolve()`.
|
||||
3. `--runtime-version <tag>` cache fallback (debug only — downloads from GitHub).
|
||||
|
||||
### Code Quality (enforced by linters)
|
||||
|
||||
Static analysis runs in CI and pre-commit. New code **must** stay within these limits:
|
||||
|
||||
@@ -92,13 +92,35 @@ Each executor uses git worktrees for workspace isolation, preventing concurrent
|
||||
|
||||
## Quick Start
|
||||
|
||||
### NPX (recommended)
|
||||
### Homebrew (macOS, Linux)
|
||||
|
||||
```bash
|
||||
npx kandev
|
||||
brew install kdlbs/kandev/kandev
|
||||
kandev
|
||||
```
|
||||
|
||||
This downloads pre-built backend + frontend bundles and starts them locally. The worktrees and sqlite db will be created in `~/.kandev` by default. Should work on macOS, Linux, and Windows (WSL or native).
|
||||
### NPX
|
||||
|
||||
```bash
|
||||
npx kandev@latest
|
||||
```
|
||||
|
||||
Requires npm 7+. Installs the CLI plus a platform-matched runtime bundle in one step.
|
||||
|
||||
### NPM (global)
|
||||
|
||||
```bash
|
||||
npm install -g kandev@latest
|
||||
kandev
|
||||
```
|
||||
|
||||
### Updates
|
||||
|
||||
- `brew upgrade kandev`
|
||||
- `npx kandev@latest` (always uses the latest published version)
|
||||
- `npm install -g kandev@latest`
|
||||
|
||||
The worktrees and sqlite db live in `~/.kandev` by default. Works on macOS, Linux, and Windows (WSL or native).
|
||||
|
||||
### From Source
|
||||
|
||||
|
||||
+24
-6
@@ -4,18 +4,36 @@ Manage tasks. Orchestrate agents. Review changes. Ship value.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Homebrew
|
||||
|
||||
```bash
|
||||
npx kandev
|
||||
brew install kdlbs/kandev/kandev
|
||||
kandev
|
||||
```
|
||||
|
||||
Downloads the latest release, starts the backend + web app, and opens your browser. Data (worktrees, SQLite DB) is stored in `~/.kandev` by default.
|
||||
### NPX (requires npm 7+)
|
||||
|
||||
```bash
|
||||
npx kandev@latest
|
||||
```
|
||||
|
||||
Either install path resolves a platform-matched runtime (Go backend, agentctl, Next.js standalone web), launches the backend + web, and opens your browser. Data (worktrees, SQLite DB) is stored in `~/.kandev` by default.
|
||||
|
||||
## Version and Updates
|
||||
|
||||
- `npx kandev` (run mode) uses the latest GitHub release bundle by default.
|
||||
- At startup, the launcher prints the resolved release tag (for example: `[kandev] release: v0.2.3 (github latest)`).
|
||||
- Use `--version <tag>` to pin a specific runtime bundle release.
|
||||
- CLI package updates are checked from npm and shown as a prompt. They are not forced.
|
||||
The package manager owns the runtime version. `kandev@X.Y.Z` ships with the matching runtime — no first-run download.
|
||||
|
||||
- **Update via Homebrew**: `brew upgrade kandev`
|
||||
- **Update via npm/npx**: `npx kandev@latest` or `npm install -g kandev@latest`
|
||||
- **Print CLI version**: `kandev --version`
|
||||
|
||||
### Advanced: pin a specific runtime tag
|
||||
|
||||
`--runtime-version <tag>` downloads a specific GitHub release runtime instead of using the installed one. For debugging compatibility issues only:
|
||||
|
||||
```bash
|
||||
kandev --runtime-version v0.16.0
|
||||
```
|
||||
|
||||
## What You Get
|
||||
|
||||
|
||||
+124
-112
@@ -1,158 +1,170 @@
|
||||
# Kandev Launcher (npx)
|
||||
# Kandev CLI (internal docs)
|
||||
|
||||
## Architecture
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["npx kandev"] --> B["npm downloads kandev package"]
|
||||
B --> C["CLI parses arguments"]
|
||||
C --> D{"Command?"}
|
||||
A["kandev"] --> B["CLI parses arguments"]
|
||||
B --> C{"Command?"}
|
||||
|
||||
D -->|run| E["Fetch latest GitHub release"]
|
||||
D -->|dev| F["Use local repo"]
|
||||
D -->|start| G["Use local build"]
|
||||
C -->|run / default| D["resolveRuntime()"]
|
||||
C -->|dev| F["Use local repo"]
|
||||
C -->|start| G["Use local build"]
|
||||
|
||||
E --> E1["Download platform zip"]
|
||||
E1 --> E2["Extract to ~/.kandev/bin/"]
|
||||
E2 --> E3["Start backend + Next.js standalone"]
|
||||
D --> D1{"KANDEV_BUNDLE_DIR set?"}
|
||||
D1 -->|yes| D2["Use env bundle (Homebrew)"]
|
||||
D1 -->|no| D3["require.resolve('@kdlbs/runtime-{platform}')"]
|
||||
D3 -->|hit| D4["Use installed npm bundle"]
|
||||
D3 -->|miss| D5{"--runtime-version given?"}
|
||||
D5 -->|yes| D6["Download from GitHub Releases (cache)"]
|
||||
D5 -->|no| D7["Throw: 'No runtime found'"]
|
||||
|
||||
D2 --> E["Start backend + Next.js standalone"]
|
||||
D4 --> E
|
||||
D6 --> E
|
||||
|
||||
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:
|
||||
This package provides the `kandev` CLI launcher. The runtime bundle (Go backend, agentctl, Next.js standalone web) is **installed by the package manager** — there is no first-run download.
|
||||
|
||||
- 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.
|
||||
Two install channels share the same release artifacts:
|
||||
|
||||
It also supports local dev and production runs from a repo checkout.
|
||||
- **npm/npx**: `kandev@X.Y.Z` declares `optionalDependencies` for `@kdlbs/runtime-{platform}@X.Y.Z`. npm 7+ filters by `os`/`cpu` and installs only the matching one.
|
||||
- **Homebrew**: `kdlbs/homebrew-kandev` formula downloads the GitHub release tarball into the Cellar and sets `KANDEV_BUNDLE_DIR`.
|
||||
|
||||
Both channels resolve to the same runtime bundle layout (`bin/kandev`, `bin/agentctl`, `web/server.js`). The CLI launcher (`runtime.ts`) abstracts over them.
|
||||
|
||||
## Artifact shapes
|
||||
|
||||
The GitHub release bundle and the npm runtime package are **different shapes** because they serve different consumers:
|
||||
|
||||
```
|
||||
# GitHub release bundle (used by Homebrew + manual installs)
|
||||
kandev/
|
||||
├── bin/{kandev,agentctl}
|
||||
├── web/server.js
|
||||
└── cli/
|
||||
├── bin/cli.js # #!/usr/bin/env node + chmod +x
|
||||
└── dist/cli.bundle.js # esbuild single-file bundle (deps inlined)
|
||||
|
||||
# npm runtime package (@kdlbs/runtime-{platform})
|
||||
@kdlbs/runtime-{platform}/
|
||||
├── bin/{kandev,agentctl}
|
||||
└── web/server.js
|
||||
```
|
||||
|
||||
The `cli/` directory is only in the GitHub bundle (Homebrew needs the launcher). For npm installs, the main `kandev` package already provides the CLI; the runtime package only ships the binaries + web bundle.
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description |
|
||||
| ------------------------ | -------------------------------------------------------- |
|
||||
| `kandev` or `kandev run` | Download and run release bundles (default) |
|
||||
| `kandev` or `kandev run` | Run from installed runtime bundle (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 |
|
||||
| Option | Description |
|
||||
| -------------------------- | ---------------------------------------------------------- |
|
||||
| `--version`, `-V` | Print CLI version and exit |
|
||||
| `--port`, `--backend-port` | Backend port |
|
||||
| `--web-internal-port` | Override internal Next.js port |
|
||||
| `--verbose`, `-v` | Show info logs |
|
||||
| `--debug` | Show debug logs + agent message dumps |
|
||||
| `--runtime-version <tag>` | **Advanced/debug**: download a specific GitHub runtime tag |
|
||||
| `--help`, `-h` | Show help |
|
||||
|
||||
## Updates (package-manager owned)
|
||||
|
||||
The CLI no longer self-updates. Updates flow through the install channel:
|
||||
|
||||
```bash
|
||||
brew upgrade kandev # Homebrew
|
||||
npm install -g kandev@latest # npm global
|
||||
npx kandev@latest # always pulls latest
|
||||
```
|
||||
|
||||
There is no `KANDEV_NO_UPDATE_PROMPT` or `KANDEV_SKIP_UPDATE` env var anymore — they're gone with the self-updater.
|
||||
|
||||
## Bundling for Homebrew
|
||||
|
||||
The Homebrew bundle uses `dist/cli.bundle.js`, an esbuild single-file output that inlines `tree-kill`, `tar`, and other Node deps. Required because the Cellar has no `node_modules`. The npm package uses the unbundled `dist/cli.js` and resolves deps via npm.
|
||||
|
||||
```bash
|
||||
pnpm -C apps/cli build # produces dist/cli.js
|
||||
pnpm -C apps/cli bundle # produces dist/cli.bundle.js (~212KB)
|
||||
```
|
||||
|
||||
Smoke test the bundle in a clean directory:
|
||||
|
||||
```bash
|
||||
mkdir /tmp/smoke && cd /tmp/smoke
|
||||
node /path/to/apps/cli/dist/cli.bundle.js --help
|
||||
```
|
||||
|
||||
If `Cannot find module 'tree-kill'` appears, the bundle is broken.
|
||||
|
||||
## Local Development
|
||||
|
||||
```bash
|
||||
# Run CLI in dev mode
|
||||
# Run CLI in dev mode (uses tsx)
|
||||
pnpm -C apps/cli dev
|
||||
|
||||
# Run with arguments
|
||||
pnpm -C apps/cli dev -- start
|
||||
pnpm -C apps/cli dev -- --backend-port 9000
|
||||
pnpm -C apps/cli dev -- --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
|
||||
```
|
||||
Releases run entirely in GitHub Actions. From the GHA UI:
|
||||
|
||||
The unified release script supports `cli`, `app`, or `both` in one flow.
|
||||
Versioning strategy:
|
||||
1. Open the **Release** workflow.
|
||||
2. Click **Run workflow**.
|
||||
3. Choose `bump` (patch / minor / major) from the dropdown.
|
||||
4. Optionally tick `dry_run` to validate without publishing.
|
||||
5. Click **Run workflow**.
|
||||
|
||||
- App release tags: `vM.m`
|
||||
- CLI npm version: `M.m.0`
|
||||
- Default bump mode: `minor`
|
||||
The workflow does everything: version bump, CHANGELOG, PR, merge, tag, build, npm publish, Homebrew tap update. See [/.github/workflows/release.yml](../../.github/workflows/release.yml).
|
||||
|
||||
Single SemVer flow: `apps/cli/package.json` version, git tag, npm packages, and Homebrew formula are all bumped to the same `X.Y.Z`.
|
||||
|
||||
Versioning:
|
||||
|
||||
- One SemVer `X.Y.Z` for everything (npm, GitHub tag, Homebrew formula)
|
||||
- Git tag format: `vX.Y.Z`
|
||||
- Legacy `vM.m` tags normalized to `M.m.0` during migration; new releases always use `vX.Y.Z`
|
||||
|
||||
## 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 |
|
||||
| Variable | Description |
|
||||
| ------------------------------------- | --------------------------------------------------------------------- |
|
||||
| `KANDEV_BUNDLE_DIR` | Force runtime bundle location (set by Homebrew wrapper, tests) |
|
||||
| `KANDEV_PORT` / `KANDEV_BACKEND_PORT` | Backend port |
|
||||
| `KANDEV_WEB_PORT` | Internal Next.js port |
|
||||
| `KANDEV_HEALTH_TIMEOUT_MS` | Override health check timeout (ms) |
|
||||
| `KANDEV_GITHUB_OWNER` | Override GitHub repo owner (default: `kdlbs`) for `--runtime-version` |
|
||||
| `KANDEV_GITHUB_REPO` | Override GitHub repo name (default: `kandev`) for `--runtime-version` |
|
||||
| `KANDEV_GITHUB_TOKEN` | Optional GitHub token for rate limits |
|
||||
|
||||
## 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) |
|
||||
| Platform | npm runtime package | GitHub asset name |
|
||||
| --------------------- | ------------------------------------------- | --------------------------- |
|
||||
| macOS (Apple Silicon) | `@kdlbs/runtime-darwin-arm64` | `kandev-macos-arm64.tar.gz` |
|
||||
| macOS (Intel) | `@kdlbs/runtime-darwin-x64` | `kandev-macos-x64.tar.gz` |
|
||||
| Linux (x64) | `@kdlbs/runtime-linux-x64` | `kandev-linux-x64.tar.gz` |
|
||||
| Linux (ARM64) | `@kdlbs/runtime-linux-arm64` | `kandev-linux-arm64.tar.gz` |
|
||||
| Windows (x64) | `@kdlbs/runtime-win32-x64` | `kandev-windows-x64.tar.gz` |
|
||||
| Windows (ARM64) | Falls back to `windows-x64` (x64 emulation) | |
|
||||
|
||||
Note: `platform.ts` uses internal naming (`macos`, `windows`); npm `os` field uses npm conventions (`darwin`, `win32`). `runtime.ts` maps between the two.
|
||||
|
||||
## npm requirements
|
||||
|
||||
The optional-dependency runtime resolution requires **npm 7 or newer**. npm 6 silently skips optional deps during `npx`, which would leave users with no runtime. `package.json` declares `engines.npm: ">=7"` to surface this at install time as a clear error.
|
||||
|
||||
+97
-76
@@ -4,17 +4,23 @@
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph CLI["npx kandev"]
|
||||
subgraph CLI["kandev"]
|
||||
run["run"]
|
||||
dev["dev"]
|
||||
start["start"]
|
||||
end
|
||||
|
||||
run --> gh["GitHub Release"]
|
||||
run --> resolve["Resolve installed runtime"]
|
||||
dev --> makedev["make dev"]
|
||||
start --> binary["Binary + next start"]
|
||||
start --> binary["Local binary + next start"]
|
||||
|
||||
gh --> supervisor
|
||||
resolve --> envvar["KANDEV_BUNDLE_DIR<br/>(Homebrew, tests)"]
|
||||
resolve --> npmpkg["@kdlbs/runtime-{platform}<br/>(npm/npx)"]
|
||||
resolve --> cache["~/.kandev/bin cache<br/>(--runtime-version only)"]
|
||||
|
||||
envvar --> supervisor
|
||||
npmpkg --> supervisor
|
||||
cache --> supervisor
|
||||
makedev --> supervisor
|
||||
binary --> supervisor
|
||||
|
||||
@@ -28,51 +34,68 @@ flowchart TB
|
||||
|
||||
## Overview
|
||||
|
||||
The Kandev CLI (`kandev`) is the primary way to run the Kandev application. It handles downloading release bundles, managing processes, and providing a unified interface for both end users and developers.
|
||||
The Kandev CLI (`kandev`) is the primary way to run the Kandev application. It launches the backend and web processes from an installed runtime bundle and provides a unified interface for end users and developers.
|
||||
|
||||
The runtime bundle (Go backend, agentctl, Next.js standalone web) is installed by your package manager — there is no first-run download.
|
||||
|
||||
## Installation
|
||||
|
||||
No installation required. Use npx:
|
||||
### Homebrew (macOS, Linux)
|
||||
|
||||
```bash
|
||||
npx kandev
|
||||
brew install kdlbs/kandev/kandev
|
||||
```
|
||||
|
||||
Or install globally:
|
||||
### NPX (requires npm 7+)
|
||||
|
||||
```bash
|
||||
npm install -g kandev
|
||||
npx kandev@latest
|
||||
```
|
||||
|
||||
`npx` installs the `kandev` CLI plus the matching `@kdlbs/runtime-{platform}` package via npm optional dependencies. Older npm versions silently skip optional deps and won't work — npm 7 is the floor.
|
||||
|
||||
### NPM (global)
|
||||
|
||||
```bash
|
||||
npm install -g kandev@latest
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Run the latest release (recommended for users)
|
||||
npx kandev
|
||||
# Run the installed runtime
|
||||
kandev
|
||||
|
||||
# Opens the app at http://localhost:37429 (or next available port)
|
||||
# Opens the app at http://localhost:38429 (or next available port)
|
||||
```
|
||||
|
||||
## Updates
|
||||
|
||||
The package manager controls the runtime version:
|
||||
|
||||
```bash
|
||||
brew upgrade kandev # Homebrew users
|
||||
npm install -g kandev@latest # global npm users
|
||||
npx kandev@latest # npx users (always latest)
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
### `kandev` / `kandev run`
|
||||
|
||||
Downloads and runs the latest release bundle from GitHub. This is the default command and recommended for end users.
|
||||
Runs the installed runtime bundle. This is the default command.
|
||||
|
||||
```bash
|
||||
npx kandev
|
||||
npx kandev run
|
||||
npx kandev run --version v0.1.0
|
||||
kandev
|
||||
kandev run
|
||||
```
|
||||
|
||||
**What happens:**
|
||||
1. Checks for CLI updates (prompts if newer version available)
|
||||
2. Downloads the platform-specific release bundle from GitHub
|
||||
3. Extracts to `~/.kandev/bin/<version>/<platform>/`
|
||||
4. Starts the backend server
|
||||
5. Waits for backend health check
|
||||
6. Starts the web app
|
||||
7. Prints URLs when ready
|
||||
1. Resolves the runtime bundle (KANDEV_BUNDLE_DIR → npm package → cache).
|
||||
2. Starts the backend server.
|
||||
3. Waits for backend health check.
|
||||
4. Starts the web app.
|
||||
5. Opens browser when ready.
|
||||
|
||||
### `kandev dev`
|
||||
|
||||
@@ -80,53 +103,49 @@ Runs the application in development mode with hot-reloading. Requires a local re
|
||||
|
||||
```bash
|
||||
# From the repo root or any subdirectory
|
||||
npx kandev dev
|
||||
kandev dev
|
||||
```
|
||||
|
||||
**What happens:**
|
||||
1. Locates the repo root (looks for `apps/backend` and `apps/web`)
|
||||
2. Runs `make dev` for the backend (Go with hot-reload)
|
||||
3. Runs `pnpm dev` for the web app (Next.js dev server)
|
||||
4. Both processes run with hot-reloading enabled
|
||||
1. Locates the repo root (looks for `apps/backend` and `apps/web`).
|
||||
2. Runs `make dev` for the backend (Go with hot-reload).
|
||||
3. Runs `pnpm dev` for the web app (Next.js dev server).
|
||||
|
||||
### `kandev start`
|
||||
|
||||
Runs the application using local production builds. Requires running `make build` first.
|
||||
|
||||
```bash
|
||||
# Build first
|
||||
make build
|
||||
|
||||
# Then start
|
||||
npx kandev start
|
||||
kandev start
|
||||
```
|
||||
|
||||
**What happens:**
|
||||
1. Locates the repo root
|
||||
2. Runs the compiled backend binary (`apps/backend/bin/kandev`)
|
||||
3. Runs `pnpm start` for the web app (Next.js production server)
|
||||
4. Both run in production mode without hot-reloading
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Description | Example |
|
||||
|--------|-------------|---------|
|
||||
| `--version <tag>` | Use a specific release version | `--version v0.1.0` |
|
||||
| `--backend-port <port>` | Override backend port | `--backend-port 18080` |
|
||||
| `--web-port <port>` | Override web port | `--web-port 13000` |
|
||||
| `--version`, `-V` | Print CLI version and exit | `kandev --version` |
|
||||
| `--port <port>` | Backend port (alias: `--backend-port`) | `--port 3000` |
|
||||
| `--web-internal-port <port>` | Override internal Next.js port | `--web-internal-port 13000` |
|
||||
| `--verbose`, `-v` | Show info logs from backend + web | `--verbose` |
|
||||
| `--debug` | Show debug logs + agent message dumps | `--debug` |
|
||||
| `--help`, `-h` | Show help | `--help` |
|
||||
| `--runtime-version <tag>` | **Advanced/debug only**: download a specific runtime tag from GitHub releases instead of using the installed runtime | `--runtime-version v0.16.0` |
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Use specific release
|
||||
npx kandev --version v0.1.0
|
||||
# Print CLI version
|
||||
kandev --version
|
||||
|
||||
# Custom ports
|
||||
npx kandev --backend-port 18080 --web-port 13000
|
||||
kandev --port 18080 --web-internal-port 13000
|
||||
|
||||
# Dev mode with custom ports
|
||||
npx kandev dev --backend-port 18080 --web-port 13000
|
||||
# Dev mode
|
||||
kandev dev --port 18080
|
||||
|
||||
# Force a specific runtime version (debug)
|
||||
kandev --runtime-version v0.16.0
|
||||
```
|
||||
|
||||
## Port Selection
|
||||
@@ -135,10 +154,9 @@ By default, the CLI automatically finds available ports:
|
||||
|
||||
| Service | Default Port | Fallback |
|
||||
|---------|--------------|----------|
|
||||
| Backend | 38429 | Auto-selects from 10000-60000 |
|
||||
| Web | 37429 | Auto-selects from 10000-60000 |
|
||||
| AgentCtl | 39429 | Auto-selects from 10000-60000 |
|
||||
| MCP Server | 40429 | Auto-selects from 10000-60000 |
|
||||
| Backend | 38429 | Auto-selects from 10000–60000 |
|
||||
| Web | 37429 | Auto-selects from 10000–60000 |
|
||||
| AgentCtl | 39429 | Auto-selects from 10000–60000 |
|
||||
|
||||
If the default port is in use, the CLI finds the next available port automatically.
|
||||
|
||||
@@ -146,25 +164,21 @@ If the default port is in use, the CLI finds the next available port automatical
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `KANDEV_GITHUB_OWNER` | Override GitHub repo owner for releases |
|
||||
| `KANDEV_GITHUB_REPO` | Override GitHub repo name for releases |
|
||||
| `KANDEV_GITHUB_TOKEN` | GitHub token for API rate limits |
|
||||
| `KANDEV_NO_UPDATE_PROMPT=1` | Disable CLI update prompts |
|
||||
| `KANDEV_BUNDLE_DIR` | Force the runtime bundle location (set by Homebrew wrapper) |
|
||||
| `KANDEV_PORT` / `KANDEV_BACKEND_PORT` | Backend port (CLI flag wins) |
|
||||
| `KANDEV_WEB_PORT` | Internal Next.js port |
|
||||
| `KANDEV_HEALTH_TIMEOUT_MS` | Override health check timeout (ms) |
|
||||
| `KANDEV_GITHUB_OWNER` / `KANDEV_GITHUB_REPO` | Override GitHub repo for `--runtime-version` downloads |
|
||||
| `KANDEV_GITHUB_TOKEN` | GitHub token for `--runtime-version` API access |
|
||||
|
||||
## Makefile Integration
|
||||
|
||||
The repo includes a Makefile that wraps the CLI for common operations:
|
||||
|
||||
```bash
|
||||
# Install deps, build, and start in production mode
|
||||
make start
|
||||
|
||||
# Run in development mode
|
||||
make dev
|
||||
|
||||
# Build everything
|
||||
make build
|
||||
make start # Production mode (after make build)
|
||||
make dev # Development mode
|
||||
make build # Build everything
|
||||
```
|
||||
|
||||
See `make help` for all available commands.
|
||||
@@ -173,7 +187,7 @@ See `make help` for all available commands.
|
||||
|
||||
| Feature | `run` | `dev` | `start` |
|
||||
|---------|-------|-------|---------|
|
||||
| Source | GitHub releases | Local repo | Local build |
|
||||
| Source | Installed runtime | Local repo | Local build |
|
||||
| Hot-reload | No | Yes | No |
|
||||
| Requires repo | No | Yes | Yes |
|
||||
| Requires build | No | No | Yes |
|
||||
@@ -181,12 +195,25 @@ See `make help` for all available commands.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "No Kandev runtime found for {platform}"
|
||||
|
||||
The CLI couldn't find an installed runtime. Install one:
|
||||
|
||||
```bash
|
||||
# via npm (requires npm 7+ for optional dep resolution)
|
||||
npx kandev@latest
|
||||
# via Homebrew
|
||||
brew install kdlbs/kandev/kandev
|
||||
```
|
||||
|
||||
If you're on npm 6 or older, optional dependencies aren't installed by `npx`. Upgrade npm: `npm install -g npm@latest`.
|
||||
|
||||
### Port Already in Use
|
||||
|
||||
The CLI automatically finds available ports. If you need a specific port:
|
||||
|
||||
```bash
|
||||
npx kandev --backend-port 18080 --web-port 13000
|
||||
kandev --port 18080
|
||||
```
|
||||
|
||||
### Backend Takes Too Long to Start
|
||||
@@ -194,15 +221,7 @@ npx kandev --backend-port 18080 --web-port 13000
|
||||
Increase the health check timeout:
|
||||
|
||||
```bash
|
||||
KANDEV_HEALTH_TIMEOUT_MS=60000 npx kandev
|
||||
```
|
||||
|
||||
### GitHub Rate Limits
|
||||
|
||||
If you hit GitHub API rate limits, provide a token:
|
||||
|
||||
```bash
|
||||
KANDEV_GITHUB_TOKEN=ghp_xxx npx kandev
|
||||
KANDEV_HEALTH_TIMEOUT_MS=60000 kandev
|
||||
```
|
||||
|
||||
### Dev Mode: "Unable to locate repo root"
|
||||
@@ -211,7 +230,7 @@ Run from within the kandev repository:
|
||||
|
||||
```bash
|
||||
cd /path/to/kandev
|
||||
npx kandev dev
|
||||
kandev dev
|
||||
```
|
||||
|
||||
### Start Mode: "Backend binary not found"
|
||||
@@ -220,12 +239,14 @@ Build the project first:
|
||||
|
||||
```bash
|
||||
make build
|
||||
npx kandev start
|
||||
kandev start
|
||||
```
|
||||
|
||||
## Data Storage
|
||||
|
||||
| Path | Contents |
|
||||
|------|----------|
|
||||
| `~/.kandev/bin/` | Downloaded release bundles |
|
||||
| `~/.kandev/bin/` | Cached downloads from `--runtime-version` (debug only) |
|
||||
| `~/.kandev/data/` | SQLite database and app data |
|
||||
| Homebrew Cellar | Installed runtime (when installed via brew) |
|
||||
| `<npm cache>/node_modules/@kdlbs/runtime-{platform}/` | Installed runtime (when installed via npm/npx) |
|
||||
|
||||
Reference in New Issue
Block a user