From 27b3a3e2ede85ce514cc5f59db9a60207887ecb9 Mon Sep 17 00:00:00 2001 From: Jer Miller Date: Sun, 5 Jul 2026 05:00:43 -0600 Subject: [PATCH] refactor(packaging): sweep install commands to the leaf package set Mechanical install-command + hint-string sweep (packaging split stage 4). Retire the `solstone[journal]` extras spelling and the `--with-executables-from solstone-journal-host` / `--include-deps` exposure flags in favor of the leaf distributions: `solstone-journal`, `solstone-journal-cuda`, and the thin `solstone` client. - INSTALL.md, README.md, CONTRIBUTING.md: install/upgrade/uninstall trios retokenized to the canonical set; exposure passages reshaped to the pip-native-vs-two-tools story; false "journal is becoming its own package" notes dropped; INSTALL.md gains a pre-split migration subsection. - docs/DOCTOR.md, docs/SOLCLI.md: host-deps guidance + distribution facts aligned to the new HOST_DEPENDENCY_REINSTALL_GUIDANCE. - docs/environment.md, docs/FIELD_JOURNAL.md: packaged install refs canonicalized. - solstone/think/doctor.py: HOST_DEPENDENCY_REINSTALL_GUIDANCE updated. - solstone/observe/model_assets.py + tests/test_model_assets.py: missing-models hint -> `pip install solstone-journal`. Co-Authored-By: Claude Opus 4.8 (1M context) --- CONTRIBUTING.md | 10 ++--- INSTALL.md | 63 +++++++++++++++++--------------- README.md | 10 ++--- docs/DOCTOR.md | 4 +- docs/FIELD_JOURNAL.md | 2 +- docs/SOLCLI.md | 4 +- docs/environment.md | 2 +- solstone/observe/model_assets.py | 2 +- solstone/think/doctor.py | 10 ++--- tests/test_model_assets.py | 2 +- 10 files changed, 55 insertions(+), 54 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0fb810133..1e9909018 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,7 +14,7 @@ Required everywhere: - ripgrep (`rg`) - ffmpeg for audio processing -Linux is the primary development platform. macOS is supported. Source-checkout installs on Apple Silicon need Xcode command line tools to build the CoreML parakeet helper; packaged host installs (`uv tool install --with-executables-from solstone-journal-host 'solstone[journal]'`) on macOS 14 or newer ship the helper as a pre-built binary. +Linux is the primary development platform. macOS is supported. Source-checkout installs on Apple Silicon need Xcode command line tools to build the CoreML parakeet helper; packaged host installs (`uv tool install solstone-journal && uv tool install solstone`) on macOS 14 or newer ship the helper as a pre-built binary. Fedora/RHEL: @@ -166,7 +166,7 @@ That target first runs `sol skills build` to regenerate the checked-in reference ## Migrating from a source install to a packaged install -A packaged host install puts `sol`, `solstone`, `journal`, and `mlx-vlm-server` on PATH directly. With uv tool, use `uv tool install --with-executables-from solstone-journal-host 'solstone[journal]'` so the host scripts from the `solstone-journal-host` dependency are exposed. It does not use the source-checkout managed wrapper, and it does not use `.venv/bin/sol`. +A packaged host install puts `sol`, `solstone`, `journal`, and `mlx-vlm-server` on PATH directly. `pip install solstone-journal` exposes those commands in one environment; uv tool and pipx expose each tool's own commands, so install both the journal tool and the thin `solstone` tool. It does not use the source-checkout managed wrapper, and it does not use `.venv/bin/sol`. `make uninstall` is disabled by design. To migrate cleanly from a source checkout to a packaged install, remove user-runtime artifacts explicitly: @@ -174,12 +174,12 @@ A packaged host install puts `sol`, `solstone`, `journal`, and `mlx-vlm-server` journal service uninstall sol skills uninstall python -m solstone.think.install_guard uninstall -uv tool install --with-executables-from solstone-journal-host 'solstone[journal]' +uv tool install solstone-journal && uv tool install solstone journal setup ``` -For pip or pipx packaged installs, use `pip install 'solstone[journal]'` or -`pipx install --include-deps 'solstone[journal]'` before `journal setup`. +For pip or pipx packaged installs, use `pip install solstone-journal` or +`pipx install solstone-journal && pipx install solstone` before `journal setup`. Your journal is preserved at `~/journal`; solstone does not remove it during install or uninstall. Do not add backwards-compatibility shims for the old source-checkout layout. This migration is a clean break. diff --git a/INSTALL.md b/INSTALL.md index 973c59aed..11e75fbcc 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -29,24 +29,22 @@ most people install solstone to **run the journal here** — the full host that transcribes, makes sense of your day, and holds everything: ```bash -pip install 'solstone[journal]' -uv tool install --with-executables-from solstone-journal-host 'solstone[journal]' -pipx install --include-deps 'solstone[journal]' +pip install solstone-journal # includes sol on PATH +uv tool install solstone-journal && uv tool install solstone # journal tool + sol tool +pipx install solstone-journal && pipx install solstone # same two-tool story ``` -Pick one installer. The quotes matter — they keep your shell from treating the -`[journal]` brackets as a glob. +Pick one installer. -A host install puts `sol`, `solstone`, `journal`, and `mlx-vlm-server` on PATH -(`~/.local/bin/` for uv tool and pipx), which most shells already include. If -not: `exec $SHELL -l` or restart your shell. - -`journal` and `mlx-vlm-server` live in the `solstone-journal-host` distribution -that `[journal]` pulls in. `pip` exposes dependency scripts natively; `uv tool` -and `pipx` need the flags shown above to expose those host commands. +A pip install of solstone-journal puts `sol`, `solstone`, `journal`, and +`mlx-vlm-server` on PATH (`~/.local/bin/` for uv tool and pipx, which most +shells already include). uv tool and pipx expose each installed tool's own +commands — the journal tool provides `journal` and `mlx-vlm-server`, and the +thin solstone tool provides `sol` and `solstone`, which is why their install +lines above are two commands. NVIDIA GPU owners who want GPU-accelerated transcription install -`solstone[journal-cuda]` **instead of** `solstone[journal]` with the same +`solstone-journal-cuda` **instead of** `solstone-journal` with the same installer command shape. ### just the `sol` client @@ -62,10 +60,7 @@ uvx solstone --help # or ephemerally — no install, one-shot ``` A thin/no-extras install carries only `sol` and `solstone`; `journal setup`, -`journal start`, and `mlx-vlm-server` require a `solstone[journal]` host install. - -(packaging note: the journal is becoming its own installable package, so this -install story will simplify — the commands above stay accurate today.) +`journal start`, and `mlx-vlm-server` require a `solstone-journal` host install. ## set up @@ -77,9 +72,9 @@ this runs the setup readiness doctor battery, confirms the journal directory at let your human know: **open http://localhost:5015 in a browser**. the first-run wizard walks them through setting their identity and connecting a gemini API key. -a `solstone[journal]` install bundles everything a journal host needs — PDF rendering, whisper, and the default CPU transcription stack are all included; `journal setup` downloads the transcription model. there are no separate à-la-carte extras to add. if the readiness doctor step (`journal doctor --readiness`) finds missing system libraries, it will tell you the exact install command to run for your platform. +a `solstone-journal` install bundles everything a journal host needs — PDF rendering, whisper, and the default CPU transcription stack are all included; `journal setup` downloads the transcription model. there are no separate à-la-carte extras to add. if the readiness doctor step (`journal doctor --readiness`) finds missing system libraries, it will tell you the exact install command to run for your platform. -Pick one of `solstone[journal]` or `solstone[journal-cuda]` — the CPU and GPU ONNX runtimes share the same files and must not both be installed. `journal doctor` reports whether the transcription runtime and model are ready. +Pick one of `solstone-journal` or `solstone-journal-cuda` — the CPU and GPU ONNX runtimes share the same files and must not both be installed. `journal doctor` reports whether the transcription runtime and model are ready. This CUDA extra is only for transcription. The Linux local model provider uses Vulkan for screen analysis, so a hardware Vulkan GPU from AMD, NVIDIA, or Intel can work; CPU/software Vulkan devices are rejected instead of falling back silently. On AMD, the local model path runs through Mesa/RADV Vulkan, while transcription stays on the bundled CPU runtime. @@ -123,27 +118,37 @@ journal observer create tmux-laptop (for observer packages, `uv tool install solstone-tmux` is also fine if you prefer uv.) +## migrating from a pre-split install + +If you installed the journal before the package split, run the one-time migration +line for your installer family, then run `journal setup`. + +```bash +pip uninstall solstone-journal-host && pip install solstone-journal +pipx uninstall solstone && pipx install solstone-journal && pipx install solstone +uv tool uninstall solstone && uv tool install solstone-journal && uv tool install solstone +``` + ## upgrading ```bash -pip install --upgrade 'solstone[journal]' && journal setup -uv tool install --upgrade --with-executables-from solstone-journal-host 'solstone[journal]' && journal setup -pipx install --force --include-deps 'solstone[journal]' && journal setup +pip install --upgrade solstone-journal && journal setup +uv tool install --upgrade solstone-journal && uv tool install --upgrade solstone && journal setup +pipx upgrade solstone-journal && journal setup ``` -Use the same installer family you used for install. The `uv tool` form must -keep `--with-executables-from solstone-journal-host`, and the pipx form must -keep `--include-deps`, so the `journal` and `mlx-vlm-server` host scripts stay -on PATH after the upgrade. For GPU transcription, replace `[journal]` with -`[journal-cuda]`. The `journal setup` step refreshes runtime artifacts and -reconciles the service unit if anything has changed. +Use the same installer family you used for install. The `uv tool` form upgrades both +the journal package and the thin `solstone` client, while the pipx form upgrades +the journal tool. For GPU transcription, upgrade `solstone-journal-cuda` instead +of `solstone-journal`. The `journal setup` step refreshes runtime artifacts and +reconciles the systemd/launchd unit if anything has changed. ## uninstall 1. remove setup-managed runtime files: `journal setup --clean-uninstall` this removes the user service, managed `~/.local/bin/sol` wrapper, user config, and setup manifest. it does not remove your journal. 2. optional: remove the installed `sol` agent skill: `sol skills uninstall`. -3. uninstall the python package: `uv tool uninstall solstone` (or `pipx uninstall solstone`). +3. uninstall the python packages: `uv tool uninstall solstone-journal && uv tool uninstall solstone` (or `pipx uninstall solstone-journal`). 4. macOS only: drag `/Applications/solstone.app` to Trash. 5. macOS only, optional: remove observer app data and the parakeet model cache: ```bash diff --git a/README.md b/README.md index b36d70385..9095968d5 100644 --- a/README.md +++ b/README.md @@ -71,23 +71,21 @@ Python 3.11+, Linux + macOS, AGPL-3.0-only, maintained by [sol pbc](https://solp run a journal here — the full host: ```bash -uv tool install --with-executables-from solstone-journal-host 'solstone[journal]' +uv tool install solstone-journal && uv tool install solstone journal setup ``` pip and pipx equivalents, followed by `journal setup`: ```bash -pip install 'solstone[journal]' -pipx install --include-deps 'solstone[journal]' +pip install solstone-journal +pipx install solstone-journal && pipx install solstone ``` -The `journal` and `mlx-vlm-server` commands live in the `solstone-journal-host` package that `[journal]` pulls in. `pip` exposes them natively; `uv tool` and `pipx` need the flag shown above. For GPU transcription, replace `[journal]` with `[journal-cuda]`. +A `pip install solstone-journal` puts `journal` and `mlx-vlm-server` on PATH natively; `uv tool` and `pipx` expose each tool's own commands, so the journal install is two commands — the journal tool plus the thin `solstone` tool. For GPU transcription, install `solstone-journal-cuda` instead. want only the thin `sol` client — to talk to a journal running elsewhere? `uv tool install solstone` (no extras), or `uvx solstone` for an ephemeral one-shot. -*(packaging note: the journal is becoming its own installable package, so this install story will simplify — the commands above stay accurate today.)* - then open http://localhost:5015 in a browser; the first-run wizard handles identity and the gemini API key. see [INSTALL.md](INSTALL.md) for prerequisites, observer install, and troubleshooting; see [CONTRIBUTING.md](CONTRIBUTING.md) if you want to develop on solstone from a source checkout. diff --git a/docs/DOCTOR.md b/docs/DOCTOR.md index 6e8be3212..becefbbd9 100644 --- a/docs/DOCTOR.md +++ b/docs/DOCTOR.md @@ -35,7 +35,7 @@ Use the diagnostic command that matches the question: `uv` exist? - `journal health` — what live supervisor status is being reported right now? -`journal`-prefixed commands, including `journal doctor` and `journal setup`, require a journal-host install because the `journal` executable ships in the `solstone-journal-host` distribution (`solstone[journal]`), not in the thin `sol` client. +`journal`-prefixed commands, including `journal doctor` and `journal setup`, require a journal-host install because the `journal` executable ships in the `solstone-journal` distribution, not in the thin `sol` client. `sol doctor` runs four checks: @@ -62,7 +62,7 @@ Use the diagnostic command that matches the question: | `feature:pdf`, `feature:whisper` | advisory | Optional extras with exact install commands. | `host_dependencies` fix guidance is: Reinstall the journal host stack: -`pip install --upgrade 'solstone[journal]'` | `uv tool install --upgrade --with-executables-from solstone-journal-host 'solstone[journal]'` | `pipx install --force --include-deps 'solstone[journal]'`. On an NVIDIA host use the 'solstone[journal-cuda]' extra instead of 'solstone[journal]'. +`pip install --upgrade solstone-journal` | `uv tool install --upgrade solstone-journal` | `pipx install --force solstone-journal`. On an NVIDIA host use `solstone-journal-cuda` instead — never install both. `journal doctor` is role-aware. If there is no local journal directory or no installed service, folder and service checks emit `skip` (`no local journal` or diff --git a/docs/FIELD_JOURNAL.md b/docs/FIELD_JOURNAL.md index b98cbaf1d..6c80298e4 100644 --- a/docs/FIELD_JOURNAL.md +++ b/docs/FIELD_JOURNAL.md @@ -23,7 +23,7 @@ git clone https://github.com/solpbc/field_journal ~/Field_Journal ### 2. Scaffold the journal -If you don't already have a configured `journal/` (identity, providers, convey secret, facets), bootstrap one the normal way first — `make install` (source checkout) or `uv tool install --with-executables-from solstone-journal-host 'solstone[journal]'` (packaged) followed by `journal setup`, then whatever initial first-run wizard work brings the journal to a usable state. `setup_field_journal.sh` only populates `chronicle/`; it expects the rest of the journal scaffolding to already exist. +If you don't already have a configured `journal/` (identity, providers, convey secret, facets), bootstrap one the normal way first — `make install` (source checkout) or `uv tool install solstone-journal && uv tool install solstone` (packaged) followed by `journal setup`, then whatever initial first-run wizard work brings the journal to a usable state. `setup_field_journal.sh` only populates `chronicle/`; it expects the rest of the journal scaffolding to already exist. ### 3. Populate chronicle from field_journal diff --git a/docs/SOLCLI.md b/docs/SOLCLI.md index 91f8f8845..fc29f57e6 100644 --- a/docs/SOLCLI.md +++ b/docs/SOLCLI.md @@ -19,7 +19,7 @@ The CLI has two tiers with distinct purposes: **Interactive entry points** (`sol chat`, `sol help`, `journal engage`) are top-level for discoverability even though they're user-facing. Agents don't invoke these. -Console scripts are split across distributions. The base `solstone` package ships `sol` and `solstone`, both pointing at `solstone.think.sol_cli:main`. The `solstone-journal-host` distribution, pulled in by `solstone[journal]` / `solstone[journal-cuda]`, ships the host-only `journal` and `mlx-vlm-server` console scripts. The dispatcher, including `journal_main()`, still lives in base `solstone.think.sol_cli`; only the console-script wrapper moved. A thin/bare install therefore has no `journal` executable on PATH. +Console scripts are split across distributions. The base `solstone` package ships `sol` and `solstone`, both pointing at `solstone.think.sol_cli:main`. The `solstone-journal` / `solstone-journal-cuda` distributions ship the host-only `journal` and `mlx-vlm-server` console scripts. The dispatcher, including `journal_main()`, still lives in base `solstone.think.sol_cli`; only the console-script wrapper moved. A thin/bare install therefore has no `journal` executable on PATH. ## Top-Level Commands (`sol `) @@ -281,7 +281,7 @@ instead of false failures. Its battery is: command when missing. `host_dependencies` fix guidance is: Reinstall the journal host stack: -`pip install --upgrade 'solstone[journal]'` | `uv tool install --upgrade --with-executables-from solstone-journal-host 'solstone[journal]'` | `pipx install --force --include-deps 'solstone[journal]'`. On an NVIDIA host use the 'solstone[journal-cuda]' extra instead of 'solstone[journal]'. +`pip install --upgrade solstone-journal` | `uv tool install --upgrade solstone-journal` | `pipx install --force solstone-journal`. On an NVIDIA host use `solstone-journal-cuda` instead — never install both. Journal-host blocker failures include invalid service config, service identity mismatch, crash loops, systemd failed state, and journal-sync conflicts. An diff --git a/docs/environment.md b/docs/environment.md index ac2910d46..7ded461f1 100644 --- a/docs/environment.md +++ b/docs/environment.md @@ -30,7 +30,7 @@ If you think you need to set `SOLSTONE_JOURNAL` from application code, fix the a ## Service Installation -There are two install paths and they handle journal resolution differently. For a fresh source checkout, `.venv/bin/journal setup` installs managed bash wrappers at `~/.local/bin/sol` and `~/.local/bin/journal`, then installs solstone as a systemd user service (Linux) or launchd agent (macOS) with convey on port 5015. For packaged host installs (`pip install 'solstone[journal]'`, `uv tool install --with-executables-from solstone-journal-host 'solstone[journal]'`, or `pipx install --include-deps 'solstone[journal]'`), `journal setup` also provisions those managed wrappers in-process, pointing them at the packaged runtime binaries. After setup, the wrappers let you use `sol` and `journal` from anywhere; override with `.venv/bin/journal setup --port 8000` on the first source-checkout run or `journal setup --port 8000` after the wrapper exists. If an existing alias is owned by another install, setup copies it to `/tmp/.old-symlink-` before atomically replacing both wrappers. Wrapper provisioning failures are non-fatal warnings so a later `journal setup` can retry. Both paths install the service. +There are two install paths and they handle journal resolution differently. For a fresh source checkout, `.venv/bin/journal setup` installs managed bash wrappers at `~/.local/bin/sol` and `~/.local/bin/journal`, then installs solstone as a systemd user service (Linux) or launchd agent (macOS) with convey on port 5015. For packaged host installs (`pip install solstone-journal`, `uv tool install solstone-journal && uv tool install solstone`, or `pipx install solstone-journal && pipx install solstone`), `journal setup` also provisions those managed wrappers in-process, pointing them at the packaged runtime binaries. After setup, the wrappers let you use `sol` and `journal` from anywhere; override with `.venv/bin/journal setup --port 8000` on the first source-checkout run or `journal setup --port 8000` after the wrapper exists. If an existing alias is owned by another install, setup copies it to `/tmp/.old-symlink-` before atomically replacing both wrappers. Wrapper provisioning failures are non-fatal warnings so a later `journal setup` can retry. Both paths install the service. Installed services invoke `~/.local/bin/journal`. They do **not** write `SOLSTONE_JOURNAL` into the service env block; the wrapper exports it before execing the venv `journal`. diff --git a/solstone/observe/model_assets.py b/solstone/observe/model_assets.py index a206f5d79..254cea9fc 100644 --- a/solstone/observe/model_assets.py +++ b/solstone/observe/model_assets.py @@ -10,7 +10,7 @@ SILERO_VAD_MODEL_FILENAME = "silero_vad_v6.onnx" _MISSING_MODELS_MESSAGE = ( "solstone-journal-models is not installed; it ships solstone's bundled " "speaker/VAD model weights and is included with a journal-host install " - "(for example: pip install 'solstone[journal]')." + "(for example: pip install solstone-journal)." ) diff --git a/solstone/think/doctor.py b/solstone/think/doctor.py index 107bf2298..9ed9fafc9 100644 --- a/solstone/think/doctor.py +++ b/solstone/think/doctor.py @@ -110,12 +110,10 @@ _HOST_DEPENDENCY_MODULES = ( ) HOST_DEPENDENCY_REINSTALL_GUIDANCE = ( "Reinstall the journal host stack: " - "pip install --upgrade 'solstone[journal]' | " - "uv tool install --upgrade --with-executables-from solstone-journal-host " - "'solstone[journal]' | " - "pipx install --force --include-deps 'solstone[journal]'. " - "On an NVIDIA host use the 'solstone[journal-cuda]' extra instead of " - "'solstone[journal]'." + "pip install --upgrade solstone-journal | " + "uv tool install --upgrade solstone-journal | " + "pipx install --force solstone-journal. " + "On an NVIDIA host use solstone-journal-cuda instead — never install both." ) SERVICE_IDENTITY_CHECK = Check("service_identity", "blocker", ("linux", "darwin")) SERVICE_RUNNING_CHECK = Check("service_running", "blocker", ("linux", "darwin")) diff --git a/tests/test_model_assets.py b/tests/test_model_assets.py index a8e15dbce..8289888c6 100644 --- a/tests/test_model_assets.py +++ b/tests/test_model_assets.py @@ -16,7 +16,7 @@ from solstone.observe.model_assets import ( MISSING_MODELS_MESSAGE = ( "solstone-journal-models is not installed; it ships solstone's bundled " "speaker/VAD model weights and is included with a journal-host install " - "(for example: pip install 'solstone[journal]')." + "(for example: pip install solstone-journal)." ) -- 2.51.2