From 7114562929aeb57a738c538d57fc78671d9c1db4 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Thu, 23 Apr 2026 02:32:51 +0800 Subject: [PATCH 1/2] chore: migrate to make, no just Signed-off-by: Chojan Shang --- AGENTS.md | 16 ++--- CONTRIBUTING.md | 16 +++-- Makefile | 56 +++++++++++++++ README.md | 15 ++-- justfile | 70 ------------------- pyproject.toml | 1 - uv.lock | 24 ------- website/AGENTS.md | 10 +++ website/DEPLOYMENT.md | 6 +- .../docs/getting-started/installation.mdx | 2 + .../content/docs/docs/guides/deployment.mdx | 4 +- .../docs/getting-started/installation.mdx | 2 + .../docs/zh-cn/docs/guides/deployment.mdx | 4 +- 13 files changed, 106 insertions(+), 120 deletions(-) create mode 100644 Makefile delete mode 100644 justfile diff --git a/AGENTS.md b/AGENTS.md index 78b8487e..c99bd860 100644 --- a/AGENTS.md +++ b/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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3ac6d39a..a57e61c1 100644 --- a/CONTRIBUTING.md +++ b/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. diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..315de3ff --- /dev/null +++ b/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 diff --git a/README.md b/README.md index 4f965c55..6e49fba5 100644 --- a/README.md +++ b/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). diff --git a/justfile b/justfile deleted file mode 100644 index a094d5d9..00000000 --- a/justfile +++ /dev/null @@ -1,70 +0,0 @@ -# Default recipe - show help -default: - @just --list - -# Install the virtual environment and install the pre-commit hooks -install: - #!/usr/bin/env bash - echo "🚀 Creating virtual environment using uv" - uv sync - echo "🚀 Installing website dependencies with pnpm" - pnpm --dir website install --frozen-lockfile - uv run prek install - -# Run code quality tools -check: - #!/usr/bin/env bash - echo "🚀 Checking lock file consistency with 'pyproject.toml'" - uv lock --locked - echo "🚀 Linting code: Running prek" - uv run prek run -a - echo "🚀 Static type checking: Running mypy" - uv run mypy src - -# Run vulture to check for unused code -vulture: - #!/usr/bin/env bash - echo "🚀 Checking for unused code with vulture" - uv run prek run vulture --hook-stage manual --all-files - -# Test the code with pytest -test: - #!/usr/bin/env bash - echo "🚀 Testing code: Running pytest" - uv run python -m pytest --doctest-modules - -# Clean build artifacts -clean-build: - #!/usr/bin/env bash - echo "🚀 Removing build artifacts" - uv run python -c "import shutil; import os; shutil.rmtree('dist') if os.path.exists('dist') else None" - -# Build wheel file -build: clean-build - #!/usr/bin/env bash - echo "🚀 Creating wheel file" - uvx --from build pyproject-build --installer uv - -# Publish a release to PyPI -publish: - #!/usr/bin/env bash - echo "🚀 Publishing." - uvx twine upload --repository-url https://upload.pypi.org/legacy/ dist/* - -# Build and publish -build-and-publish: build publish - -# Test if documentation can be built without warnings or errors -docs-test: - #!/usr/bin/env bash - pnpm --dir website build - -# Build and serve the documentation -docs: - #!/usr/bin/env bash - pnpm --dir website dev --host - -# Preview the production documentation build -docs-preview: - #!/usr/bin/env bash - pnpm --dir website preview --ip 0.0.0.0 diff --git a/pyproject.toml b/pyproject.toml index f9c42555..425c3deb 100644 --- a/pyproject.toml +++ b/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", ] diff --git a/uv.lock b/uv.lock index 7ba9e886..5ab2c14a 100644 --- a/uv.lock +++ b/uv.lock @@ -234,7 +234,6 @@ dev = [ { name = "pytest" }, { name = "pytest-asyncio" }, { name = "ruff" }, - { name = "rust-just" }, { name = "tox-uv" }, { name = "types-pyyaml" }, ] @@ -266,7 +265,6 @@ dev = [ { name = "pytest", specifier = ">=7.2.0" }, { name = "pytest-asyncio", specifier = ">=1.3.0" }, { name = "ruff", specifier = ">=0.11.5" }, - { name = "rust-just", specifier = ">=1.42.0" }, { name = "tox-uv", specifier = ">=1.11.3" }, { name = "types-pyyaml", specifier = ">=6.0.12" }, ] @@ -1716,28 +1714,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/58/ed/dea90a65b7d9e69888890fb14c90d7f51bf0c1e82ad800aeb0160e4bacfd/ruff-0.15.10-py3-none-win_arm64.whl", hash = "sha256:601d1610a9e1f1c2165a4f561eeaa2e2ea1e97f3287c5aa258d3dab8b57c6188", size = 11035607, upload-time = "2026-04-09T14:05:47.593Z" }, ] -[[package]] -name = "rust-just" -version = "1.49.0" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/97/f2/c1612952bb4de508e89a1a10ff8bc7fbf18160bf75bcf502264e04e0c3ba/rust_just-1.49.0.tar.gz", hash = "sha256:a3b5f16f5e131b7ea86720510798688c146ae4859a92410e1ed5d13e79ddcd0f", size = 1912238, upload-time = "2026-04-09T05:38:11.349Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/14/d9/5f7fa48d2903345a885a4d93a5c3a75d14acad8211a6e41bc24c6221f479/rust_just-1.49.0-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:c91cad7bbb9280b74f0f6761b4b9f91ab8b30e6fd29885d463fcee011c1c28a8", size = 1976290, upload-time = "2026-04-09T05:38:09.916Z" }, - { url = "https://files.pythonhosted.org/packages/2e/2a/bcac6a5091dbbdac5536a28f5c5747a7ce4d251e2273a2586a03b6e15fd1/rust_just-1.49.0-py3-none-macosx_11_0_arm64.whl", hash = "sha256:655b50c40a6a43464a3b217874d81623143c95fecfcaca476d5552d3cdb035b3", size = 1839665, upload-time = "2026-04-09T05:38:20.522Z" }, - { url = "https://files.pythonhosted.org/packages/e3/ec/8dff9bcc9327cea9990e0c88932e554131afcf4b593e5163de1c994bd325/rust_just-1.49.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:4cd8b7a1d7a84f95ebba73a2038eed1d89e2ae397f80e89c99a25e34808206f8", size = 1927171, upload-time = "2026-04-09T05:38:15.779Z" }, - { url = "https://files.pythonhosted.org/packages/93/a1/d7cc40ec13a702f1fecc4f14d5d6e34f31e557a8cf4e14fd4de0e364d9eb/rust_just-1.49.0-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:505f7d9c132f8ba747b35c7ba92c5bca13950875b4040a4c0c1a5aa1b94bc3f6", size = 1904953, upload-time = "2026-04-09T05:38:12.779Z" }, - { url = "https://files.pythonhosted.org/packages/fb/0f/19be2e9f6682ae4941b4ea98cefa9c6f3f41ca32f134407651fdc52c38c9/rust_just-1.49.0-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:e82381559658f83c5888a36f420b4bec6e4abdecef7ad40d4c74a90d80551e96", size = 2108508, upload-time = "2026-04-09T05:37:59.591Z" }, - { url = "https://files.pythonhosted.org/packages/58/7f/d073eaf6729e4c239c9935bd1a94ea19e9dd9504242e077d651e41fdb386/rust_just-1.49.0-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:b3dd978725e4ed8d34d0518acf34e6cd9e215bb24737b62eed87fec3d4747507", size = 2177355, upload-time = "2026-04-09T05:38:01.573Z" }, - { url = "https://files.pythonhosted.org/packages/5e/69/d0331a382c8c6a5390164c591dba4ca74e31c903389fc92dea895654ee67/rust_just-1.49.0-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:ad50c7d05fedc4d87abd6cc44127e1ddc246be56f5f11fad05ac00e0b66c33e4", size = 2120914, upload-time = "2026-04-09T05:38:19.023Z" }, - { url = "https://files.pythonhosted.org/packages/25/f4/997605402b8502f7637875c1159a6dd9c0dd74d0493d49cf858ea5463b6a/rust_just-1.49.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b2e0f03694f030f3f39f7bba53545d6038eddb87fa0a3383cd9f3a55dcf4ed26", size = 2090756, upload-time = "2026-04-09T05:37:57.931Z" }, - { url = "https://files.pythonhosted.org/packages/c0/bc/bd90073c7f2725eeef93a9816c8c2d49410339d1863d385071b7960677e5/rust_just-1.49.0-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:d105edbcc02e278fa3eb6730a8be2c4576e5ce4f52f43706ae5e7a07af112278", size = 1949099, upload-time = "2026-04-09T05:38:17.346Z" }, - { url = "https://files.pythonhosted.org/packages/a8/54/cf57ec444c1fa851525d651f67f7eb4c1b52e701568638d2784fe690fd62/rust_just-1.49.0-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:6bc0c84f1c1bc5c13b66f6947e21e7828f0df0048cff40565ed7b574e04cfd16", size = 1931798, upload-time = "2026-04-09T05:38:14.114Z" }, - { url = "https://files.pythonhosted.org/packages/ef/a3/7a5ec8e401f4b069d6577c8cc72592264ec220eabd0e767db7aad22a6586/rust_just-1.49.0-py3-none-musllinux_1_2_i686.whl", hash = "sha256:abe84305fc4591c95f4dc0a02f61228a4bf64a4a5d5558cbf4777401147f9681", size = 2080900, upload-time = "2026-04-09T05:38:03.31Z" }, - { url = "https://files.pythonhosted.org/packages/98/65/817e047a93e0d9c4faa5eb9de05db4f1631f419f5dccc94a4e16dda79309/rust_just-1.49.0-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:a814fccd210727d587ba058efb2c54e772a102a73bc729759cf96667d1d4f599", size = 2155307, upload-time = "2026-04-09T05:38:05.214Z" }, - { url = "https://files.pythonhosted.org/packages/ef/e0/e7678714597383cf9ccd76ed7819b1cf6e3d079c80bdf476496634be36de/rust_just-1.49.0-py3-none-win32.whl", hash = "sha256:9ace425355867b3249b9c61ed7c23a2f482259345de3e649c262deb1263c321d", size = 1855815, upload-time = "2026-04-09T05:38:06.595Z" }, - { url = "https://files.pythonhosted.org/packages/08/85/ce1299f161ea7094c175953d1cb17aaf19900e9ec23edfbe728b27cd2cbd/rust_just-1.49.0-py3-none-win_amd64.whl", hash = "sha256:e34a1845394d947f2f7e47ba8c9fe9d323bb6c21af4aa5dca5168507ecdb7eba", size = 2064187, upload-time = "2026-04-09T05:38:08.316Z" }, -] - [[package]] name = "shellingham" version = "1.5.4" diff --git a/website/AGENTS.md b/website/AGENTS.md index 3a4eec51..5d201a91 100644 --- a/website/AGENTS.md +++ b/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 `` 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 diff --git a/website/DEPLOYMENT.md b/website/DEPLOYMENT.md index 8aa4d118..0f69fe39 100644 --- a/website/DEPLOYMENT.md +++ b/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. diff --git a/website/src/content/docs/docs/getting-started/installation.mdx b/website/src/content/docs/docs/getting-started/installation.mdx index 6d46a8b6..d5d7376a 100644 --- a/website/src/content/docs/docs/getting-started/installation.mdx +++ b/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. diff --git a/website/src/content/docs/docs/guides/deployment.mdx b/website/src/content/docs/docs/guides/deployment.mdx index 227b71fa..6538d416 100644 --- a/website/src/content/docs/docs/guides/deployment.mdx +++ b/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 ``` diff --git a/website/src/content/docs/zh-cn/docs/getting-started/installation.mdx b/website/src/content/docs/zh-cn/docs/getting-started/installation.mdx index 4e3e5b68..50c9490e 100644 --- a/website/src/content/docs/zh-cn/docs/getting-started/installation.mdx +++ b/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。 diff --git a/website/src/content/docs/zh-cn/docs/guides/deployment.mdx b/website/src/content/docs/zh-cn/docs/guides/deployment.mdx index d7050117..48d7cb9e 100644 --- a/website/src/content/docs/zh-cn/docs/guides/deployment.mdx +++ b/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 ``` From cfeaa16b6fe7ad41d5c9ac1306fe88f20770486e Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Thu, 23 Apr 2026 02:33:14 +0800 Subject: [PATCH 2/2] fix: make make docs works --- website/astro.config.mjs | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/website/astro.config.mjs b/website/astro.config.mjs index 85926111..407cb23e 100644 --- a/website/astro.config.mjs +++ b/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',