chore: migrate to make, no just

AGENTS.md

@@ -16,18 +16,18 @@ Tests live in `tests/`. The website and docs runtime lives in `website/`.
 
 ## Build, Test, and Development Commands
 
-- `uv sync`: install or update dependencies.
-- `just install`: sync dependencies and install `prek` hooks.
+- `uv sync`: install or update the Python environment; enough to run Bub from source or for deployment-only hosts.
+- `make install`: full local development bootstrap; sync Python deps, install website deps, and install `prek` hooks.
 - `uv run bub chat`: run the interactive CLI.
 - `uv run bub gateway`: start channel listener mode.
 - `uv run bub run "hello"`: run one inbound message through the full framework pipeline.
 - `uv run bub hooks`: inspect discovered hook bindings.
-- `uv run ruff check .`: lint checks.
-- `uv run mypy src`: static type checks.
-- `uv run pytest -q`: run the main test suite.
-- `just test`: run pytest with doctests enabled.
-- `just check`: lock validation, lint, and typing.
-- `just docs` / `just docs-test`: serve or build the Astro website/docs in `website/`.
+- `uv run ruff check .`: run Ruff directly when you only want lint feedback.
+- `uv run mypy src`: run mypy directly against `src/`.
+- `uv run pytest -q`: run the main test suite without doctests.
+- `make test`: run pytest with doctests enabled.
+- `make check`: lock validation, `prek`, and typing.
+- `make docs` / `make docs-test` / `make docs-preview`: serve, build, or preview the Astro website/docs in `website/`.
 
 ## Coding Style & Naming Conventions
 

CONTRIBUTING.md

@@ -65,11 +65,11 @@ cd bub
 Then, install the Python and website environments with:
 
 ```bash
-just install
+make install
 ```
 
 4. If you only need the Python environment, `uv sync` is still enough. The
-   full `just install` path also installs the new website dependencies and
+   full `make install` path also installs the new website dependencies and
    sets up `prek`.
 
 5. Create a branch for local development:
@@ -85,19 +85,25 @@ Now you can make your changes locally.
 7. When you're done making changes, check that your changes pass the formatting tests.
 
 ```bash
-just check
+make check
 ```
 
 Now, validate that all unit tests are passing:
 
 ```bash
-just test
+make test
 ```
 
 9. If your change touches the website/docs experience, also build the Astro site:
 
 ```bash
-just docs-test
+make docs-test
+```
+
+If you need to inspect the production-style site locally, run:
+
+```bash
+make docs-preview
 ```
 
 10. Before raising a pull request you should also run tox.

Makefile

@@ -0,0 +1,56 @@
+.DEFAULT_GOAL := help
+
+.PHONY: help install check vulture test clean-build build publish build-and-publish docs-test docs docs-preview
+
+help: ## Show available targets
+	@awk 'BEGIN {FS = ":.*## "}; /^[a-zA-Z0-9_-]+:.*## / {printf "%-20s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+install: ## Sync Python deps, install website deps, and install prek hooks
+	@echo "==> Syncing Python dependencies with uv"
+	uv sync
+	@echo "==> Installing website dependencies with pnpm"
+	pnpm --dir website install --frozen-lockfile
+	@echo "==> Installing prek hooks"
+	uv run prek install
+
+check: ## Validate lockfile, run prek across the repo, and type-check src
+	@echo "==> Verifying uv.lock matches pyproject.toml"
+	uv lock --locked
+	@echo "==> Running prek hooks"
+	uv run prek run -a
+	@echo "==> Running mypy on src"
+	uv run mypy src
+
+vulture: ## Run the optional unused-code check
+	@echo "==> Running vulture via prek"
+	uv run prek run vulture --hook-stage manual --all-files
+
+test: ## Run pytest with doctests enabled
+	@echo "==> Running pytest with doctests"
+	uv run python -m pytest --doctest-modules
+
+clean-build: ## Remove local build artifacts
+	@echo "==> Removing dist/"
+	rm -rf dist
+
+build: clean-build ## Build source and wheel distributions
+	@echo "==> Building package distributions"
+	uv build
+
+publish: ## Publish the contents of dist/ with uv
+	@echo "==> Publishing dist/ with uv"
+	uv publish
+
+build-and-publish: build publish ## Build distributions, then publish them
+
+docs-test: ## Build the website/docs bundle
+	@echo "==> Building website/"
+	BUB_ASTRO_IMAGE_MODE=build pnpm --dir website build
+
+docs: ## Start the website/docs development server
+	@echo "==> Starting website dev server"
+	BUB_ASTRO_IMAGE_MODE=dev pnpm --dir website dev --host
+
+docs-preview: ## Preview the production website/docs build
+	@echo "==> Starting website preview server"
+	BUB_ASTRO_IMAGE_MODE=build pnpm --dir website preview --ip 0.0.0.0

README.md

@@ -28,9 +28,11 @@ Or from source:
 ```bash
 git clone https://github.com/bubbuild/bub.git
 cd bub
-uv sync
+uv sync  # enough to run Bub from source
 ```
 
+For local development, use `make install` instead so the website toolchain and `prek` hooks are installed too.
+
 ```bash
 uv run bub chat                         # interactive session
 uv run bub run "summarize this repo"    # one-shot task
@@ -137,12 +139,11 @@ Read more:
 ## Development
 
 ```bash
-just install
-uv run ruff check .
-uv run mypy src
-uv run pytest -q
-just docs
-just docs-test
+make install
+make check
+make test
+make docs
+make docs-test
 ```
 
 See [CONTRIBUTING.md](https://github.com/bubbuild/bub/blob/main/CONTRIBUTING.md).

pyproject.toml

@@ -56,7 +56,6 @@ dev = [
     "types-PyYAML>=6.0.12",
     "mypy>=0.991",
     "ruff>=0.11.5",
-    "rust-just>=1.42.0",
     "prek>=0.3.1",
     "pytest-asyncio>=1.3.0",
 ]

website/AGENTS.md

@@ -43,6 +43,16 @@ pnpm build            # production build
 pnpm preview          # preview production build
 ```
 
+## Image Handling
+
+- Prefer the standard `Image` component from `astro:assets` for local raster assets used by pages and shared UI.
+- Do not replace local logo or illustration components with raw `<img>` just to work around Cloudflare adapter behavior.
+- The repository intentionally splits image handling in `astro.config.mjs`:
+  - `BUB_ASTRO_IMAGE_MODE=dev`: Cloudflare image service, so `make docs` works under Node without `cloudflare:workers` import failures.
+  - `BUB_ASTRO_IMAGE_MODE=build`: compile-time optimization with passthrough runtime, so `make docs-test`, `make docs-preview`, and production serve stable built asset URLs.
+- `Makefile` is the source of truth for that mode selection. `process.argv` command detection only exists as a fallback for direct `pnpm dev` / `pnpm build` usage inside `website/`.
+- If you change adapter image settings, re-verify all three paths: `make docs`, `make docs-test`, and `make docs-preview`.
+
 ---
 
 ## Directory Structure

website/DEPLOYMENT.md

@@ -43,9 +43,9 @@ GitHub Actions.
 
 The local developer entrypoints now target the new site:
 
-- `just docs`
-- `just docs-test`
-- `just docs-preview`
+- `make docs`
+- `make docs-test`
+- `make docs-preview`
 
 The CI docs check also builds `website/` instead of MkDocs.
 

website/astro.config.mjs

@@ -5,9 +5,19 @@ import tailwindcss from '@tailwindcss/vite';
 import starlight from '@astrojs/starlight';
 import cloudflare from '@astrojs/cloudflare';
 
+const astro_image_mode =
+  process.env.BUB_ASTRO_IMAGE_MODE ?? (process.argv.includes('dev') ? 'dev' : 'build');
+
+const image_service =
+  astro_image_mode === 'dev' ? 'cloudflare' : { runtime: 'passthrough' };
+
 export default defineConfig({
   // SSG by default; landing pages opt-in to SSR via `export const prerender = false`.
   adapter: cloudflare({
+    // Prefer an explicit mode from the calling command so local docs workflows
+    // stay deterministic. Fall back to the Astro command name for direct
+    // `pnpm dev` / `pnpm build` usage inside `website/`.
+    imageService: image_service,
     prerenderEnvironment: 'node',
   }),
   site: process.env.SITE_URL ?? 'https://bub.build',

website/src/content/docs/docs/getting-started/installation.mdx

@@ -18,6 +18,8 @@ uv sync
 uv run bub chat
 ```
 
+If you are setting up a contributor workspace rather than just running Bub from source, use `make install` instead. That also installs the website toolchain and `prek` hooks used by the repo.
+
 ## Core commands
 
 - `uv run bub chat` starts the interactive CLI.

website/src/content/docs/docs/guides/deployment.mdx

@@ -20,6 +20,8 @@ uv sync
 cp env.example .env
 ```
 
+Use `uv sync` here on purpose: deployment hosts only need the Python runtime. `make install` is the developer bootstrap path when you also need the website/docs toolchain locally.
+
 Minimum `.env` example:
 
 ```bash
@@ -102,7 +104,7 @@ git fetch --all --tags
 git pull
 uv sync
 uv run ruff check .
-uv run mypy
+uv run mypy src
 uv run pytest -q
 ```
 

website/src/content/docs/zh-cn/docs/getting-started/installation.mdx

@@ -18,6 +18,8 @@ uv sync
 uv run bub chat
 ```
 
+如果你是在准备贡献开发环境，而不只是从源码运行 Bub，请改用 `make install`。它还会安装仓库使用的站点工具链和 `prek` hooks。
+
 ## 常用命令
 
 - `uv run bub chat` 启动交互式 CLI。

website/src/content/docs/zh-cn/docs/guides/deployment.mdx

@@ -20,6 +20,8 @@ uv sync
 cp env.example .env
 ```
 
+这里刻意使用 `uv sync`：部署主机只需要 Python 运行时。如果你还要在本地维护网站或文档，再使用 `make install` 作为开发环境入口。
+
 最小 `.env` 示例：
 
 ```bash
@@ -102,7 +104,7 @@ git fetch --all --tags
 git pull
 uv sync
 uv run ruff check .
-uv run mypy
+uv run mypy src
 uv run pytest -q
 ```