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:
José Almeida
2026-05-03 17:47:03 +01:00
parent 8db50791d6
commit 98550f5e66
5 changed files with 300 additions and 197 deletions
+30
View File
@@ -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:
+25 -3
View File
@@ -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
View File
@@ -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
View File
@@ -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
View File
@@ -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) |