TalkPipe 1.0.2b1__tar.gz → 1.0.2b2__tar.gz

{talkpipe-1.0.2b1 → talkpipe-1.0.2b2}/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 ## Unreleased
 
+- **App Center: a launch opens the page of a released application that does
+  not open its own.** A second newcomer run against the PyPI releases. The
+  catalog's `opens_browser` describes the newest version of an application,
+  and the released writing assistant 1.1.0 has no browser-opening at all, so
+  a launch reported "is running at ..." and nothing appeared. `opens_browser`
+  now also takes a version (`"1.1.1"`): the first one that opens its own tab,
+  with the App Center opening the page for older installed versions; the
+  writing assistant's entry says `"1.1.1"`. Also: an action that fails ends
+  on a `==> Failed:` line, the counterpart of `==> Done:`, and its toast is
+  titled Failed rather than Finished; when all the App Center knows is that
+  something answers on an application's port (no 200 from the health path,
+  and not a process it started), `launch` and `stop` say "something answers
+  on port 8002" instead of stating that the application is running; `l` and
+  `o` on an application that is not installed both say to install it (`o`
+  used to say "launch it first", and `l` then "not installed"); `list` sizes
+  its columns from their content, so `installed (pre-release)` no longer
+  pushes its row out of line; the screen moves the detail pane under the
+  table below 140 columns, where a fixed side pane cut the Running and
+  Launcher columns off at the widths most terminals have; and a Linux
+  launcher for a package that ships no icon names a standard generic one,
+  which the README already promised.
+- **App Center: the release channel launches, and the way back to it
+  works.** Found by a newcomer run against the released applications rather
+  than the checkouts. A catalog `health` path that answers 404 no longer
+  counts as "down": the catalog describes the newest version, and the
+  released vault 1.0.0 and writing assistant 1.1.0 serve their ports without
+  the routes their catalog entries name, so on the default channel every
+  launch was reported as a failure while the app sat open in the browser —
+  and from there `open` refused, a second launch treated the app as "another
+  program" on its port, started a second copy on the next one, overwrote the
+  pid record, and `stop` killed the wrong one. Any HTTP answer on the port
+  now counts as running, and a launch never starts a second copy while the
+  pid file names a live process of the App Center's own. Leaving the
+  experimental channel (`e` again, `--no-experimental`) passes
+  `--reinstall`: `uv tool install --upgrade` never moves a package backwards,
+  so the switch silently kept the beta, reported "already the newest version",
+  forgot the channel record, and left the row offering the release as an
+  "upgrade" that the next `i` could not perform. If a fresh resolution still
+  lands on a pre-release, the App Center says so and keeps the record. A
+  pre-release with no record (installed by hand, or by an earlier copy) now
+  counts as being on the experimental channel, and `(pre-release)` describes
+  the installed version rather than the run's flag. Also: uninstall stops an
+  instance the App Center started before removing its environment; PyPI
+  lookups are no longer capped at 1 MiB, which blanked the latest version and
+  summary of any long-lived package (ruff's record is over 6 MB); `latest`
+  reads `?` rather than `None (<date>)` on the experimental channel; the
+  table's columns grow to fit `installed (pre-release)` instead of clipping
+  it; `c Stop` appears in the footer while the row's app is one the App
+  Center started; the uninstall question wraps; `i`, `l`, `x`, and `o` on the
+  App Center's own row say to move to an application's row instead of doing
+  nothing; the `list` hint no longer names a `talkpipe-appcenter` command
+  that the documented `uv run <url>` never creates; the language-model note
+  mentions an Ollama server on another computer; and the documented uv floor
+  (0.7) is checked, with the version named in the error — only when the
+  version parses, so a stand-in whose `--version` answers with words is not
+  mistaken for an old uv.
 - **Deprecated: omitting the `|` between an input source and the first
   segment.** `INPUT FROM echo[data="1,2"] print` has always parsed as though
   the pipe were there — an accident of the grammar, and an inconsistent one,
@@ -26,20 +82,58 @@
   take the channel by name — `install.sh --experimental`, or
   `TALKPIPE_APPCENTER_CHANNEL=experimental` for both scripts, the only
   mechanism Windows has since a piped `irm | iex` cannot receive arguments.
-
-  Installing pre-release *applications* is a separate choice, so that a
-  released App Center can install betas and a beta one installs releases unless
-  told otherwise: `--experimental` (or `--pre`), before or after the
-  subcommand, passes `--prerelease allow` to uv — which covers the application
-  and its dependencies, since a pre-release application may require a
-  pre-release library. The choice is recorded per application beside the saved
-  catalogs, because uv replays its own recorded settings for `uv tool upgrade`
-  but not for the `uv tool install --upgrade` the App Center runs; without the
-  record, a later upgrade would quietly reinstall the newest release over a
-  pre-release. `--no-experimental` leaves the channel and forgets the record.
-  On that channel the App Center no longer claims to know the latest version,
-  since PyPI's is the newest *release* and not an upgrade target for a
-  pre-release: the row reads `installed (pre-release)`.
+  That variable chooses only which copy of the App Center runs; the App
+  Center itself does not read it.
+
+  **Any one copy of the App Center installs either the release or the
+  pre-release of each application**, so a released App Center can install
+  betas and a beta one installs releases unless told otherwise. On the
+  screen the choice is a `Channel` column and two keys: `e` on an
+  application's row toggles its channel between `stable` and `pre-release`
+  and installs nothing, and `i` installs (or switches, or upgrades) from
+  whichever channel the row shows — choosing and acting are separate keys,
+  because one key that changed what you were looking at and installed it in
+  the same stroke proved confusing. The Status column says where the two
+  disagree (`installed (pre-release)`, `release available`), and the detail
+  pane repeats the channel. On the command line, `--experimental` (or
+  `--pre`), before or after the subcommand, chooses and installs in one.
+  Both pass `--prerelease allow` to uv — which covers the application and
+  its dependencies, since a pre-release application may require a
+  pre-release library. The choice is recorded per application beside the
+  saved catalogs, because uv replays its own recorded settings for `uv tool
+  upgrade` but not for the `uv tool install --upgrade` the App Center runs;
+  without the record, a later upgrade would quietly reinstall the newest
+  release over a pre-release. Installing the release again (`e` then `i`, or
+  `--no-experimental`) forgets the record. On the pre-release channel the
+  App Center no longer claims to know the latest version, since PyPI's is
+  the newest *release* and not an upgrade target for a pre-release: the row
+  reads `installed (pre-release)`.
+
+- **Fixed: the App Center never said an install had finished.** uv's output
+  scrolled through the log for minutes and then simply stopped, and its own
+  last lines start with "Installed", so the App Center's summary of what had
+  happened was one indistinguishable line in the middle of it — leaving
+  "is it still working?" unanswered. Every action now ends with a line marked
+  `==> Done:` that says what it did (`==> Done: Installed talkpipe-vault
+  1.0.0.`), placed last, after any notes about what the application still
+  needs. On the screen a notification carries the same news over the top of
+  the log, so an install walked away from still reports itself — including
+  when it failed, which the screen also never used to say out loud.
+
+- **Fixed: the App Center left a launch that hit a busy port to time out.** An
+  application whose port is already held by another program — a second copy of
+  it, or an unrelated server — either failed to bind or quietly relocated to a
+  port the App Center was not watching; both ended the same way, in a
+  thirty-second wait and "did not answer on port 8001". A web app's port is now
+  checked before it is started: when something else holds it, the App Center
+  finds the next free port above it and starts the app there, announcing the
+  move, and records that port so status, the browser, and `open` all follow the
+  app to where it actually runs. Doing so needs the new catalog key
+  `port_option` — the option the app takes a port on, `--port` for all three
+  bundled applications; without it the conflict is reported immediately rather
+  than launched into. A server that dies at startup for any other reason is
+  also reported as soon as it exits, with the last lines of its log, instead of
+  being waited out.
 
 - **Fixed: `appcenter/install.sh` exited with status 2 instead of starting the
   App Center** whenever the process had no controlling terminal — a CI runner, a

{talkpipe-1.0.2b1 → talkpipe-1.0.2b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: talkpipe
-Version: 1.0.2b1
+Version: 1.0.2b2
 Summary: Python internal and external DSL for writing generative AI analytics
 Author-email: Travis Bauer <tlbauer@sandia.gov>
 Maintainer-email: Travis Bauer <tlbauer@sandia.gov>
@@ -148,8 +148,13 @@ Entry points for different usage scenarios, from interactive development to prod
   Each release attaches the version-stamped file, so the URL above needs a full
   release that post-dates the App Center — against an older one, or where the
   only such release so far is a pre-release, it returns "Not Found" and uv
-  reports that as a `SyntaxError`. Pre-releases are served by the experimental
-  channel instead (`releases/download/experimental/talkpipe_appcenter.py`; see
+  reports that as a `SyntaxError`. Pre-releases *of the App Center itself* are
+  served by the experimental channel instead
+  (`releases/download/experimental/talkpipe_appcenter.py`). Either copy
+  installs the release or the pre-release of each application — press `e` on
+  its row to choose the channel and `i` to install, or pass
+  `--experimental` — so you never need a particular copy to
+  get a beta of an application (see
   [Channels](appcenter/README.md#channels-stable-and-experimental)). From a
   checkout of this branch, run the file directly:
   `uv run appcenter/talkpipe_appcenter.py`.

{talkpipe-1.0.2b1 → talkpipe-1.0.2b2}/README.md

@@ -79,8 +79,13 @@ Entry points for different usage scenarios, from interactive development to prod
   Each release attaches the version-stamped file, so the URL above needs a full
   release that post-dates the App Center — against an older one, or where the
   only such release so far is a pre-release, it returns "Not Found" and uv
-  reports that as a `SyntaxError`. Pre-releases are served by the experimental
-  channel instead (`releases/download/experimental/talkpipe_appcenter.py`; see
+  reports that as a `SyntaxError`. Pre-releases *of the App Center itself* are
+  served by the experimental channel instead
+  (`releases/download/experimental/talkpipe_appcenter.py`). Either copy
+  installs the release or the pre-release of each application — press `e` on
+  its row to choose the channel and `i` to install, or pass
+  `--experimental` — so you never need a particular copy to
+  get a beta of an application (see
   [Channels](appcenter/README.md#channels-stable-and-experimental)). From a
   checkout of this branch, run the file directly:
   `uv run appcenter/talkpipe_appcenter.py`.

{talkpipe-1.0.2b1 → talkpipe-1.0.2b2}/appcenter/README.md

@@ -44,6 +44,72 @@ uv run appcenter/talkpipe_appcenter.py
 
 ## Channels: stable and experimental
 
+**Any one copy of the App Center installs either the release or the
+pre-release of each application.** You never need a different copy of the App
+Center to get a beta of the vault, and running a beta of the App Center does
+not put betas of the applications on your computer. The two are separate
+choices, and only the second one comes up in normal use.
+
+### Which versions of the applications it installs
+
+Every application installs as its newest **release** unless you ask for its
+pre-release. On the screen the choice is a column of the table, `Channel`,
+and two keys: `e` on an application's row toggles its channel between
+`stable` and `pre-release` (installing nothing), and `i` installs — or
+switches, or upgrades — from whichever channel the row shows. So to try the
+vault's beta, press `e` then `i` on its row; to go back, `e` then `i` again.
+The Status column says where the two disagree: `installed (pre-release)`
+while a beta is installed on the pre-release channel, `release available`
+once the release channel is chosen over it (when PyPI knows of one). With
+several applications selected, `e` puts them all on the pre-release channel,
+unless every one of them is there already, in which case all back. From the
+command line, ask with `--experimental` (or `--pre`), before or after the
+subcommand:
+
+```bash
+uv run <url> --experimental install vault
+uv run <url> install vault --pre
+```
+
+That passes `--prerelease allow` to uv, which applies to the application **and
+its dependencies** — a pre-release vault may require a pre-release talkpipe, and
+a narrower setting would reject it and fail to resolve at all.
+
+The choice is remembered per application, in `channels.txt` beside the saved
+catalogs, so a later `upgrade` keeps it: uv replays its own recorded settings
+for `uv tool upgrade`, but the App Center runs `uv tool install --upgrade`,
+which takes them from the command line, so without the record an upgrade would
+reinstall the newest release over your pre-release. A pre-release that has no
+record — installed by hand with uv, say — counts as being on the channel all
+the same: the version decides, so the App Center never offers an application's
+own release to it as an "upgrade". Choose the release channel again with `e`
+on the screen (then `i` to install it) or with `--no-experimental` on the
+command line; installing the release forgets the record, and so does
+`uninstall`. Going back reinstalls the application's environment (`uv tool
+install --reinstall`): uv never moves a package backwards on its own, and an
+installed pre-release satisfies the requirement, so only a resolution from
+scratch puts the release over it. If even that lands on a pre-release — an
+application whose only releases so far are betas — the App Center says so and
+leaves the choice standing, rather than reporting the switch as done.
+
+On that channel the App Center stops claiming to know the newest version —
+PyPI's own "latest" is the newest *release*, which is not an upgrade target
+for a pre-release — so the row reads `installed (pre-release)` with `?` for
+latest, and `info` prints the channel.
+
+`--experimental` placed before `ui` (or given with no subcommand) sets the
+channel for every install of that screen session and says so in the title;
+`e` then declines, since one flag for the run and a choice per application
+would contradict each other — the footer leaves the key out and pressing it
+says why. Start without the flag to choose per application.
+
+`--experimental` before `install`, or `--pre` after it, is the command line's
+`e` and `i` in one: it both chooses the channel for that application and
+installs from it.
+
+### Which copy of the App Center you run
+
+This choice matters only while no full release carries the App Center.
 `releases/latest` is the newest release GitHub does *not* consider a
 pre-release, so those URLs serve the last full release even while a beta is
 out — and if the only release carrying the App Center is a beta, they return
@@ -70,31 +136,11 @@ $env:TALKPIPE_APPCENTER_CHANNEL="experimental"
 powershell -ExecutionPolicy Bypass -c "irm .../install.ps1 | iex"
 ```
 
-**Which copy you run and which versions it installs are separate choices.**
-A released App Center can install pre-release applications, and a pre-release
-one installs releases unless told otherwise. Ask for pre-release applications
-with `--experimental` (or `--pre`), before or after the subcommand:
-
-```bash
-uv run <url> --experimental install vault
-uv run <url> install vault --pre
-```
-
-That passes `--prerelease allow` to uv, which applies to the application **and
-its dependencies** — a pre-release vault may require a pre-release talkpipe, and
-a narrower setting would reject it and fail to resolve at all.
-
-The choice is remembered per application, in `channels.txt` beside the saved
-catalogs, so a later `upgrade` keeps it: uv replays its own recorded settings
-for `uv tool upgrade`, but the App Center runs `uv tool install --upgrade`,
-which takes them from the command line, so without the record an upgrade would
-reinstall the newest release over your pre-release. Leave the channel with
-`--no-experimental`, which also forgets the record; so does `uninstall`.
-
-On that channel the App Center stops claiming to know the newest version —
-PyPI's own "latest" is the newest *release*, which is not an upgrade target
-for a pre-release — so the row reads `installed (pre-release)` with `?` for
-latest, and `info` prints the channel.
+Both forms choose only which copy of the file runs. The App Center itself does
+not read `TALKPIPE_APPCENTER_CHANNEL`, so the pre-release copy fetched this way
+installs releases of the applications exactly like the released copy does,
+until you choose the pre-release channel with `e` (and install with `i`) or
+pass `--experimental` for one of them.
 
 The experimental channel is published from github.com only; the Gitea mirror
 attaches no release assets.
@@ -107,11 +153,12 @@ desktop launcher. Keys:
 |---|---|
 | `i` | Install (or upgrade) the app under the cursor, or every selected app |
 | `u` | Upgrade only apps that are installed |
+| `e` | Choose the app's channel, `stable` or `pre-release` (the `Channel` column); `i` then installs from it (see [Channels](#channels-stable-and-experimental)) |
 | `x` | Uninstall (asks first; your data stays) |
 | `l` | Launch. Web apps start in the background and open in your browser |
 | `o` | Open a running web app in the browser |
 | `s` | Add or remove a desktop launcher (menu entry, `~/Applications`, or Start Menu) |
-| `c` | Stop a web app the App Center started |
+| `c` | Stop a web app the App Center started — the footer shows it while the row's app is one it started |
 | `space` | Select for a batch install |
 | `r` | Refresh |
 | `q` | Quit |
@@ -119,6 +166,15 @@ desktop launcher. Keys:
 The last row is the App Center itself: press `s` there to give the App Center a launcher
 of its own, so nobody has to type a URL twice.
 
+An install can run for minutes, and uv's output scrolls through the pane at
+the bottom of the screen while it does. **You do not have to read it to know
+when it is over.** The App Center's own lines are the ones that begin `==>`,
+and the last one of an action begins `==> Done:` and says what happened —
+`==> Done: Installed talkpipe-vault 1.0.0.` — or `==> Failed:` and says what
+did not. A notification says the same thing over the screen, so an install
+you walked away from is still reporting itself when you come back. The same
+markers end the run in the subcommands below.
+
 ## Without the screen
 
 Every action is also a subcommand, for scripts and for people who prefer
@@ -128,6 +184,7 @@ typing. Arguments after `sh -s --` pass straight through the bootstrap script.
 uv run <url> list                  # every app and its status (--json for machines)
 uv run <url> info vault
 uv run <url> install vault writing-assistant
+uv run <url> install vault --experimental   # its pre-release; --no-experimental returns to releases
 uv run <url> upgrade --all
 uv run <url> launch vault
 uv run <url> stop vault
@@ -144,29 +201,52 @@ curl -fsSL .../install.sh | sh -s -- install vault
 
 - **Applications install with `uv tool install`**, each into its own
   environment with its own Python. Nothing else on the computer is touched,
-  and uninstalling removes exactly that environment and its commands. User
-  data (the vault's `~/.talkpipe-vault`, the writing assistant's
-  `~/.writing_assistant`) is never deleted; the App Center tells you where it is.
+  and uninstalling removes exactly that environment and its commands (stopping
+  the app first if the App Center started it). User data (the vault's
+  `~/.talkpipe-vault`, the writing assistant's `~/.writing_assistant`) is never
+  deleted; the App Center tells you where it is.
 - **Re-running an install upgrades.** "Latest" is read from PyPI every time
   the App Center starts, so the screen always knows whether an upgrade exists.
 - **Launchers open a visible terminal** on purpose: the applications have no
   tray icon or Quit command, so that window is how you stop them and see
   their messages. The launcher targets the stable `~/.local/bin` command, so
   it survives upgrades.
+- **A busy port moves the app, it does not sink the launch.** When something
+  else already holds a web app's port, the App Center starts it on the next
+  free port above it, says which one it used, and opens and tracks the app
+  there. That needs the catalog's `port_option` (the option the app takes its
+  port on); without it, the conflict is reported straight away instead of
+  waiting out a server that will never come up. Either way you get an answer
+  in seconds, with the last lines of the app's log when it failed to start.
+  An app the App Center itself started is never treated as "another program"
+  on its port: while that process is alive, a second launch reports it
+  instead of starting a second copy beside it.
+- **"Running" means something answers on the app's port.** A catalog `health`
+  path that answers 200 settles it; one that answers with any other status
+  does not count against the app, because the catalog describes the newest
+  version and an older release may serve the same port without that route.
+  The price is that an unrelated program on the port is not told apart — the
+  App Center would rather open the wrong page than call a running app down and
+  start a second one — so when that is all it knows (no 200 from the health
+  path, and not a process it started itself), its messages say "something
+  answers on port 8002" rather than naming the app.
 - **Language models are not installed.** The catalog says which apps need a
   language model; the App Center detects a local Ollama and shows its download
-  link when it is missing, or you enter an OpenAI or Anthropic key in the app's
-  own settings.
+  link when it is missing. An Ollama server on another computer, or an OpenAI
+  or Anthropic key, is entered in the app's own settings.
 - **The App Center needs the network** to start (uv fetches the file) and to show
   latest versions. Set `TALKPIPE_APPCENTER_OFFLINE=1` to skip the PyPI lookups;
   versions then show as `?`.
-- **`TALKPIPE_APPCENTER_CHANNEL=experimental`** defaults both the copy the
-  bootstrap scripts run and the versions it installs to the pre-release channel
-  (see [Channels](#channels-stable-and-experimental)). `UV_PRERELEASE` is uv's
-  own equivalent and is not used here, so that the setting reaches only the
-  installs meant to have it; setting it yourself is a power-user escape hatch.
+- **`TALKPIPE_APPCENTER_CHANNEL=experimental`** makes the bootstrap scripts
+  run the pre-release copy of the App Center, and nothing more: which versions
+  of the applications it installs is chosen per application with `e` (then
+  `i`) or `--experimental` (see [Channels](#channels-stable-and-experimental)).
+  `UV_PRERELEASE` is uv's own setting and is not used here, so that pre-release
+  resolution reaches only the installs meant to have it; setting it yourself
+  is a power-user escape hatch.
 
-uv is the only prerequisite. It must be at least 0.7.
+uv is the only prerequisite. It must be at least 0.7; the App Center checks,
+and says so if yours is older.
 
 ## The catalog: listing any pip-installable application
 
@@ -197,8 +277,16 @@ command = "vault-server"          # required; the console script to launch
 args = ["--resume"]
 kind = "web"                      # web | cli | tui (default cli)
 port = 8002                       # web only
-health = "/api/health"            # optional; else /health, /api/health, then TCP
-opens_browser = true              # the app opens its own tab; the App Center won't
+port_option = "--port"            # optional; how to ask the app for another port
+                                  #   when this one is taken. Absent: a taken
+                                  #   port is reported instead of launched into.
+health = "/api/health"            # optional; a path that answers 200 when up. Any
+                                  #   HTTP answer on the port counts too (an older
+                                  #   release may lack the route); absent, anything
+                                  #   listening on the port counts.
+opens_browser = true              # the app opens its own tab; the App Center won't.
+                                  #   A version ("1.1.1") means from that version
+                                  #   on; older installs get the page opened for them.
 icon = "talkpipe_vault/apps/static/icon-256.png"   # a PNG inside the package
 data = ["~/.talkpipe-vault"]      # shown on uninstall, never deleted
 needs = ["ollama"]                # detected and explained, never installed

{talkpipe-1.0.2b1 → talkpipe-1.0.2b2}/appcenter/install.ps1

@@ -13,12 +13,19 @@ runs in its own cached environment:
 To act without the screen, run that `uv run` line yourself with arguments,
 e.g. `uv run <url> install vault` (a piped `irm | iex` cannot receive them).
 
-For pre-release versions, set the channel in the environment first -- the only
+The App Center it runs comes from the latest full release. To run the
+pre-release copy of the App Center itself instead (needed only while no full
+release carries it yet), set the channel in the environment first -- the only
 way here, since a piped `irm | iex` takes no arguments:
 
   $env:TALKPIPE_APPCENTER_CHANNEL="experimental"
   powershell -ExecutionPolicy Bypass -c "irm .../install.ps1 | iex"
 
+That chooses only which copy of the App Center runs. Either copy installs the
+release version of every application unless told otherwise: press `e` on an
+application's row, or run `uv run <url> install <app> --experimental`, to get
+its pre-release from any copy.
+
 uv is the only thing this script installs. The App Center installs applications
 with `uv tool install`, each into its own environment; nothing else on the
 machine is touched.
@@ -28,8 +35,11 @@ $ErrorActionPreference = "Stop"
 $AppCenterUrl = "https://github.com/sandialabs/talkpipe/releases/latest/download/talkpipe_appcenter.py"
 $AppCenterExperimentalUrl = "https://github.com/sandialabs/talkpipe/releases/download/experimental/talkpipe_appcenter.py"
 
-# `releases/latest` is the newest release GitHub does not consider a pre-release,
-# so it cannot serve a beta; the experimental release is where those assets go.
+# Which copy of the App Center to run. `releases/latest` is the newest release
+# GitHub does not consider a pre-release, so it cannot serve a beta; the
+# experimental release is where those assets go. The App Center itself does not
+# read the variable: the copy chosen here installs release applications unless
+# asked per application.
 if ($env:TALKPIPE_APPCENTER_CHANNEL -eq "experimental") { $AppCenterUrl = $AppCenterExperimentalUrl }
 
 function Start-AppCenter {

{talkpipe-1.0.2b1 → talkpipe-1.0.2b2}/appcenter/install.sh

@@ -7,11 +7,19 @@
 #
 #   curl -fsSL .../install.sh | sh -s -- install vault
 #
-# For pre-release versions, pass --experimental first, or set
+# The App Center it runs comes from the latest full release. To run the
+# pre-release copy of the App Center itself instead (needed only while no full
+# release carries it yet), pass --experimental first, or set
 # TALKPIPE_APPCENTER_CHANNEL=experimental in the environment:
 #
 #   curl -fsSL .../install.sh | sh -s -- --experimental
 #
+# That chooses only which copy of the App Center runs. Either copy installs the
+# release version of every application unless told otherwise: press `e` on an
+# application's row to choose its pre-release channel and `i` to install from
+# it, or pass `install <app> --experimental`, to get its pre-release from any
+# copy.
+#
 # What it does: installs uv (https://docs.astral.sh/uv/) into ~/.local/bin if it
 # is missing, then hands over to the App Center itself, one Python file that uv runs
 # in its own cached environment:
@@ -38,18 +46,19 @@ download() {
 }
 
 main() {
-    # Channel choice. `releases/latest` is the newest release GitHub does not
-    # consider a pre-release, so it cannot serve a beta at all; the experimental
-    # release is where those assets go. A channel name rather than a URL, on
-    # purpose: this script runs what it downloads, so the URLs it will fetch stay
-    # the two literals above.
+    # Which copy of the App Center to run. `releases/latest` is the newest
+    # release GitHub does not consider a pre-release, so it cannot serve a beta
+    # at all; the experimental release is where those assets go. A channel name
+    # rather than a URL, on purpose: this script runs what it downloads, so the
+    # URLs it will fetch stay the two literals above. The choice ends here: the
+    # App Center does not read the variable, and the copy it picks installs
+    # release applications unless asked per application.
     if [ "${1:-}" = "--experimental" ]; then
         shift
         TALKPIPE_APPCENTER_CHANNEL=experimental
     fi
     if [ "${TALKPIPE_APPCENTER_CHANNEL:-}" = "experimental" ]; then
         APPCENTER_URL="$APPCENTER_EXPERIMENTAL_URL"
-        export TALKPIPE_APPCENTER_CHANNEL
     fi
 
     local_bin="$HOME/.local/bin"

{talkpipe-1.0.2b1 → talkpipe-1.0.2b2}/appcenter/talkpipe.toml

@@ -14,11 +14,18 @@
 #   args           launcher arguments (default [])
 #   kind           "web" (serves a page), "cli", or "tui" (default "cli")
 #   port           web only, required for web
-#   health         web only; a path that answers 200 when up. Absent: /health,
-#                  then /api/health, then a plain TCP connect are tried.
+#   port_option    web only; the option that sets the app's port, e.g. "--port".
+#                  With it the App Center starts the app on the next free port
+#                  when the default one is taken; without it a taken port is
+#                  reported instead.
+#   health         web only; a path that answers 200 when up. Any HTTP answer
+#                  on the port counts as running too (an older release may lack
+#                  the route); absent, anything listening on the port counts.
 #   url            web only; default "http://127.0.0.1:{port}/"
 #   opens_browser  web only; true when the app opens the browser itself on
-#                  start, so the App Center does not open a second tab (default false)
+#                  start, so the App Center does not open a second tab (default
+#                  false). A version ("1.1.1") means from that version on: the
+#                  App Center opens the page itself for older installed versions.
 #   icon           a PNG inside the installed package (site-packages-relative);
 #                  a .ico beside it is used for Windows. Absent or wrong: a
 #                  generic icon is used.
@@ -42,6 +49,7 @@ command = "vault-server"
 args = ["--resume"]
 kind = "web"
 port = 8002
+port_option = "--port"
 health = "/api/health"
 opens_browser = true
 icon = "talkpipe_vault/apps/static/icon-256.png"
@@ -55,8 +63,9 @@ package = "talkpipe-writing-assistant"
 command = "writing-assistant"
 kind = "web"
 port = 8001
+port_option = "--port"
 health = "/health"
-opens_browser = true
+opens_browser = "1.1.1"
 icon = "writing_assistant/app/static/android-chrome-512x512.png"
 data = ["~/.writing_assistant"]
 needs = ["ollama"]
@@ -68,4 +77,5 @@ package = "talkpipe[all]"
 command = "chatterlang_workbench"
 kind = "web"
 port = 4143
+port_option = "--port"
 icon = "talkpipe/app/static/talkpipe_logo.png"