Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 64 additions & 0 deletions .github/workflows/docs-search.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
name: Test optional LanceDB documentation search

on:
pull_request:
paths:
- "comfy_cli/docs/**"
- "comfy_cli/command/docs.py"
- "comfy_cli/schemas/docs.json"
- "comfy_cli/docs/search/**"
- "packages/comfy-cli-docs-search/**"
- "scripts/build_docs_lancedb.py"
- "scripts/set_release_version.py"
- "tests/comfy_cli/test_docs*.py"
- "docs/search-sources.json"
- "pyproject.toml"
- "uv.lock"
- ".github/workflows/docs-search.yml"
push:
branches: [main]
paths:
- "comfy_cli/docs/**"
- "comfy_cli/command/docs.py"
- "comfy_cli/schemas/docs.json"
- "packages/comfy-cli-docs-search/**"
- "scripts/build_docs_lancedb.py"
- "scripts/set_release_version.py"
- "tests/comfy_cli/test_docs*.py"
- "docs/search-sources.json"
- "pyproject.toml"
- "uv.lock"
- ".github/workflows/docs-search.yml"
workflow_dispatch:

permissions:
contents: read

jobs:
docs-search:
env:
PYTHONUTF8: "1"
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v7

- uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
with:
enable-cache: true
python-version: '3.10'

- name: Install optional search dependencies
run: uv sync --extra dev --extra docs-search --locked

- name: Build the pinned offline pack
run: uv run --locked --extra dev --extra docs-search python scripts/build_docs_lancedb.py

- name: Check the generated pack
run: uv run --locked --extra dev --extra docs-search python scripts/build_docs_lancedb.py --check

- name: Test lexical, semantic, and hybrid retrieval
run: uv run --locked --extra dev --extra docs-search pytest tests/comfy_cli/test_docs.py tests/comfy_cli/test_docs_lancedb.py tests/comfy_cli/command/test_docs_cli.py tests/comfy_cli/output/test_discovery.py tests/comfy_cli/output/test_envelope_schemas.py -q
65 changes: 52 additions & 13 deletions .github/workflows/publish_package.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,10 @@ jobs:
with:
python-version: '3.12'

- name: Install build and tomlkit dependencies
run: python -m pip install --upgrade pip build tomlkit
- name: Install build and LanceDB pack dependencies
run: >-
python -m pip install --upgrade pip build tomlkit jsonschema
"lancedb==0.25.0" "pyarrow>=16,<25" "onnxruntime>=1.23.2,<1.24" "tokenizers>=0.15,<1"

- name: Extract version from tag
id: get_version
Expand All @@ -31,18 +33,21 @@ jobs:
VERSION="${VERSION#v}"
echo "VERSION=${VERSION}" >> $GITHUB_ENV

- name: Update version in pyproject.toml
- name: Set matching CLI and docs-pack versions
run: python scripts/set_release_version.py "${VERSION}"

- name: Check bundled documentation
run: python scripts/build_docs_bundle.py --check

- name: Build and validate offline LanceDB docs pack
run: |
python -c "
import tomlkit
with open('pyproject.toml', 'r') as f:
content = tomlkit.load(f)
content['project']['version'] = '${{ env.VERSION }}'
with open('pyproject.toml', 'w') as f:
tomlkit.dump(content, f)
"

- name: Build distribution
python scripts/build_docs_lancedb.py
python scripts/build_docs_lancedb.py --check

- name: Build the version-matched docs-search package
run: python -m build --sdist --wheel --outdir dist/ packages/comfy-cli-docs-search

- name: Build comfy-cli distribution
run: python -m build --sdist --wheel --outdir dist/

# - name: Publish distribution to TestPyPI for Validation
Expand Down Expand Up @@ -94,3 +99,37 @@ jobs:

- name: Test Comfy CLI Help
run: comfy --help

test-docs-search-installation:
name: Test optional LanceDB docs search from PyPI
needs: build-n-publish-pypi
runs-on: ubuntu-latest
steps:
- name: Set up Python
uses: actions/setup-python@v7
with:
python-version: '3.11'

- name: Extract version from tag
id: get_version
run: |
VERSION="${GITHUB_REF#refs/tags/}"
VERSION="${VERSION#v}"
echo "VERSION=${VERSION}" >> $GITHUB_ENV

- name: Install optional docs-search extra
run: |
for attempt in 1 2 3 4 5 6 7 8; do
if pip install --no-cache-dir "comfy-cli[docs-search]==${VERSION}"; then
exit 0
fi
echo "Attempt ${attempt}: package not yet available on PyPI, waiting 15s..."
sleep 15
done
echo "::error::Failed to install comfy-cli[docs-search]==${VERSION} after 8 attempts"
exit 1

- name: Search the shipped corpus offline
run: |
comfy --json docs status
comfy --json docs search "stuck job wait timeout" --mode hybrid
3 changes: 3 additions & 0 deletions .github/workflows/pytest.yml
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,9 @@ jobs:
- name: Install dependencies
run: uv sync --extra dev --locked

- name: Check bundled documentation
run: uv run python scripts/build_docs_bundle.py --check

- name: Run tests
env:
PYTHONPATH: ${{ github.workspace }}
Expand Down
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,8 @@ sdist/
var/
wheels/
pip-wheel-metadata/
packages/comfy-cli-docs-search/src/comfy_cli_docs_search/assets/docs-search-pack.tar.gz
packages/comfy-cli-docs-search/src/comfy_cli_docs_search/assets/manifest.json
share/python-wheels/
*.egg-info/
.installed.cfg
Expand All @@ -76,4 +78,3 @@ requirements.compiled
override.txt
.coverage
coverage.xml

32 changes: 32 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -241,6 +241,38 @@ scope in the command module, or import them inside the command function.
`tests/comfy_cli/test_import_budget.py` fails if `comfy --version` starts
importing them.

### Updating searchable agent documentation

`comfy docs` indexes a curated allowlist of README sections, `docs/json-output.md`,
and the shipped agent skill files. When changing an included source, rebuild the
checked-in corpus and verify it is current:

```bash
python scripts/build_docs_bundle.py
python scripts/build_docs_bundle.py --check
```

Add or remove sources in `docs/search-sources.json`; the generator fails when a
selected README heading is missing. Keep generated IDs, excerpts, and content
derived from the Markdown rather than maintaining a second copy.

The optional LanceDB pack stores chunks and precomputed vectors alongside the
pinned BGE query encoder. Test the hybrid path from an isolated environment
with the extra enabled:

```bash
uv sync --locked --extra dev --extra docs-search
python scripts/build_docs_lancedb.py # fetches the pinned model for local pack creation
python scripts/build_docs_lancedb.py --check
uv run --locked --extra dev --extra docs-search pytest tests/comfy_cli/test_docs_lancedb.py
```

The build downloads the pinned ONNX model once and creates ignored pack assets;
search then runs from those local files. Release automation builds the same
archive from the pinned source revision, validates it against the current corpus,
and publishes the version-matched companion package with comfy-cli. PyPI must
trust the release workflow for both project names before the next release.

## Important notes

- Use `typer` for all command args management
Expand Down
9 changes: 9 additions & 0 deletions MANIFEST.in
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
include docs/search-sources.json
include docs/json-output.md
include scripts/build_docs_bundle.py
include scripts/build_docs_lancedb.py
include scripts/set_release_version.py
include packages/comfy-cli-docs-search/pyproject.toml
include packages/comfy-cli-docs-search/README.md
include packages/comfy-cli-docs-search/MODEL-LICENSE.txt
recursive-include packages/comfy-cli-docs-search/src *.py *.typed
22 changes: 22 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -665,6 +665,28 @@ Enrichment only ever reads the cache, so no command waits on a fetch. The cache
refreshes during `comfy skills install` and in the background during
`comfy launch`, or on demand with `comfy knowledge status --refresh`.

## Searching the CLI docs

Search the CLI guides and installed agent guides locally. BM25 works with the
base CLI. The optional extra adds a version-matched LanceDB pack and local
query encoder for offline semantic and hybrid search:

```bash
pip install 'comfy-cli[docs-search]' # optional; includes the version-matched offline pack
comfy --json docs status
comfy --json docs search "workflow hangs on a cloud timeout" --mode hybrid
comfy --json docs show "SECTION_ID"
```

`docs status` reports which modes this install can use. Search results include
a section ID, source location, and a short excerpt. Pass the ID to `docs show`
to read the full section; use `--max-chars` and `--offset` to page through a
long section. The docs command needs no ComfyUI workspace, and queries never
download a model. Results describe this comfy-cli release. Without the optional
pack, `--mode auto` uses BM25 and reports why semantic search is unavailable.
Agents can search each part of a larger question, read the relevant sections,
and reformulate a missed search once with a comfy command or flag.

## Analytics

Analytics are **opt-in and off by default**. The first time you run the CLI in an
Expand Down
11 changes: 8 additions & 3 deletions comfy_cli/cmdline.py
Original file line number Diff line number Diff line change
Expand Up @@ -357,7 +357,7 @@ def _maybe_nudge_setup(ctx: typer.Context, renderer) -> None:
# can be closed independently of stdout (`comfy install 2>&-`, where CPython
# sets `sys.stderr = None`). A bare `.isatty()` there would kill the command
# from the onboarding nudge of all places. See `caller.stream_is_tty`.
if sub in (None, "setup") or not renderer.is_pretty() or not stream_is_tty(getattr(sys, "stderr", None)):
if sub in (None, "setup", "docs") or not renderer.is_pretty() or not stream_is_tty(getattr(sys, "stderr", None)):
return
try:
from comfy_cli.credentials import get_session
Expand Down Expand Up @@ -523,12 +523,16 @@ def entry(
rprint(cli_version)
ctx.exit(0)

workspace_manager.setup_workspace_manager(workspace, here, recent, skip_prompt)
# Documentation lookup is self-contained: it must work from any directory
# without resolving or prompting for a ComfyUI workspace.
docs_command = ctx.invoked_subcommand == "docs"
if not docs_command:
workspace_manager.setup_workspace_manager(workspace, here, recent, skip_prompt)

# `comfy setup` owns the telemetry consent decision as a branded wizard step
# (with full disclosure). Suppress the bare global prompt for that one command
# so the user is asked exactly once, in the right place — not pre-empted here.
if ctx.invoked_subcommand != "setup":
if ctx.invoked_subcommand not in {"setup", "docs"}:
tracking.prompt_tracking_consent(skip_prompt, default_value=enable_telemetry)

_maybe_nudge_setup(ctx, renderer)
Expand Down Expand Up @@ -2253,6 +2257,7 @@ def standalone(
"comfy_cli.command.knowledge",
help="Inspect the curated model-knowledge bundle: status, resolve an alias, ranked picks per capability.",
),
"docs": LazySubcommand("comfy_cli.command.docs", help="Search and read the documentation bundled with comfy-cli."),
"workflow": LazySubcommand(
"comfy_cli.command.workflow", help="Slot-based editing of frontend-format ComfyUI workflows."
),
Expand Down
Loading
Loading