From 98550f5e66c2e25b08fdab39618bb1981a50a175 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Almeida?= Date: Sun, 3 May 2026 17:47:03 +0100 Subject: [PATCH] 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 docs with --version (CLI semver) + --runtime-version (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. --- AGENTS.md | 30 +++++ README.md | 28 ++++- apps/cli/README.md | 30 ++++- apps/cli/README_internal.md | 236 +++++++++++++++++++----------------- docs/cli.md | 173 ++++++++++++++------------ 5 files changed, 300 insertions(+), 197 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bfe39f030c..42dcd27818 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 ` 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: diff --git a/README.md b/README.md index 9ee11f277a..6d0af035c6 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/apps/cli/README.md b/apps/cli/README.md index e65a916fcd..334169ef11 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -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 ` 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 ` 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 diff --git a/apps/cli/README_internal.md b/apps/cli/README_internal.md index 3b33a0b7f7..7779383417 100644 --- a/apps/cli/README_internal.md +++ b/apps/cli/README_internal.md @@ -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///`. -- 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: -> . 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 ` | Release tag to install (default: latest) | -| `--backend-port ` | Override backend port | -| `--web-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 ` | **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. diff --git a/docs/cli.md b/docs/cli.md index 8ec15e2757..b3d9371578 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -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
(Homebrew, tests)"] + resolve --> npmpkg["@kdlbs/runtime-{platform}
(npm/npx)"] + resolve --> cache["~/.kandev/bin cache
(--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///` -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 ` | Use a specific release version | `--version v0.1.0` | -| `--backend-port ` | Override backend port | `--backend-port 18080` | -| `--web-port ` | Override web port | `--web-port 13000` | +| `--version`, `-V` | Print CLI version and exit | `kandev --version` | +| `--port ` | Backend port (alias: `--backend-port`) | `--port 3000` | +| `--web-internal-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 ` | **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) | +| `/node_modules/@kdlbs/runtime-{platform}/` | Installed runtime (when installed via npm/npx) |