launchline 0.2.1.dev0__tar.gz → 0.4.0__tar.gz

launchline-0.4.0/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

launchline-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+'on':
+  workflow_call: null
+  workflow_dispatch: null
+  push:
+    branches:
+    - main
+  pull_request:
+    branches:
+    - main
+permissions:
+  contents: read
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  check:
+    name: Python (${{ matrix.os }}, ${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+        - ubuntu-latest
+        - windows-latest
+        - macos-latest
+        python:
+        - '3.12'
+        - '3.13'
+        - '3.14'
+    steps:
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      with:
+        persist-credentials: false
+        ref: ${{ github.event.pull_request.head.sha || github.sha }}
+    - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e
+      with:
+        python-version: ${{ matrix.python }}
+    - run: uv sync --locked --group dev
+    - run: uv run poe check
+    - run: uv build
+    - run: uv run python scripts/package_smoke.py
+    - run: uv run poe mutation
+      if: matrix.os == 'windows-latest'
+    - name: Check seeded menu mutations
+      run: uv run poe mutation-menus
+      if: matrix.os == 'windows-latest'
+    - name: Test results
+      if: always()
+      uses: mikepenz/action-junit-report@6ef3fdcfcd5f0b5d14df3e659ef19b8c6820f93d
+      with:
+        report_paths: junit.xml
+        annotate_only: true
+        check_annotations: false
+        check_retries: false
+        require_tests: true
+    - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9
+      if: always()
+      with:
+        name: evidence-${{ matrix.os }}-${{ matrix.python }}
+        path: 'junit.xml
+
+          docs/validation/*json
+
+          '
+        if-no-files-found: error

launchline-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,234 @@
+name: Release
+'on':
+  push:
+    branches:
+    - main
+  workflow_dispatch:
+    inputs:
+      force-patch:
+        description: Force patch bump when no releasable commits exist
+        type: boolean
+        default: false
+permissions:
+  contents: read
+concurrency:
+  group: release
+  cancel-in-progress: false
+jobs:
+  target:
+    if: github.ref == 'refs/heads/main' && github.actor == 'mikejhill' && github.triggering_actor == 'mikejhill'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    outputs:
+      version: ${{ steps.semrel.outputs.version }}
+    steps:
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      with:
+        persist-credentials: false
+        fetch-depth: 0
+        ref: ${{ github.sha }}
+    - name: Download checksum-pinned semantic-release CLI
+      shell: bash
+      run: "set -euo pipefail\ndest=\"$RUNNER_TEMP/semantic-release-v2.31.0\"\ncurl --fail --silent --show-error --location\
+        \ --proto '=https' --tlsv1.2 \\\n  https://github.com/go-semantic-release/semantic-release/releases/download/v2.31.0/semantic-release_v2.31.0_linux_amd64\
+        \ \\\n  --output \"$dest\"\nprintf '%s  %s\\n' 'b8f518b1aeb1d1742f4e6e91a179b707cea4309a64fe3854f465bf724f04f6d3'\
+        \ \"$dest\" | sha256sum --check --strict\nchmod 0755 \"$dest\"\n"
+    - name: Preload verified runtime plugins
+      run: python3 scripts/prepare_semrel.py
+    - name: Determine version without publishing
+      id: semrel
+      shell: bash
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+        FORCE_PATCH: ${{ inputs.force-patch || false }}
+      run: 'set -euo pipefail
+
+        args=(--dry --allow-initial-development-versions --changelog release-changelog.md --allow-no-changes --plugin-resolver-disable-batch-prefetch)
+
+        if [ "$FORCE_PATCH" = true ]; then args+=(--force-bump-patch-version); fi
+
+        "$RUNNER_TEMP/semantic-release-v2.31.0" "${args[@]}"
+
+        python3 scripts/release_version.py
+
+        '
+    name: Target
+  ci:
+    name: Python (${{ matrix.os }}, ${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+        - ubuntu-latest
+        - windows-latest
+        - macos-latest
+        python:
+        - '3.12'
+        - '3.13'
+        - '3.14'
+    steps:
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      with:
+        persist-credentials: false
+        ref: ${{ github.sha }}
+    - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e
+      with:
+        python-version: ${{ matrix.python }}
+    - run: uv sync --locked --group dev
+    - run: uv run poe check
+    - run: uv build
+    - run: uv run python scripts/package_smoke.py
+    - run: uv run poe mutation
+      if: matrix.os == 'windows-latest'
+    - name: Check seeded menu mutations
+      run: uv run poe mutation-menus
+      if: matrix.os == 'windows-latest'
+    - name: Test results
+      if: always()
+      uses: mikepenz/action-junit-report@6ef3fdcfcd5f0b5d14df3e659ef19b8c6820f93d
+      with:
+        report_paths: junit.xml
+        annotate_only: true
+        check_annotations: false
+        check_retries: false
+        require_tests: true
+    - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9
+      if: always()
+      with:
+        name: evidence-${{ matrix.os }}-${{ matrix.python }}
+        path: 'junit.xml
+
+          docs/validation/*json
+
+          '
+        if-no-files-found: error
+    needs: target
+    if: needs.target.outputs.version != ''
+  build:
+    needs:
+    - target
+    - ci
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    outputs:
+      artifact-id: ${{ steps.dist.outputs.artifact-id }}
+    steps:
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      with:
+        persist-credentials: false
+        fetch-depth: 0
+        ref: ${{ github.sha }}
+    - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e
+    - name: Build tested version without publishing credentials
+      run: '[[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || exit 1
+
+        uv sync --locked --group dev
+
+        uv run poe check
+
+        python3 - <<''PY''
+
+        import os,pathlib
+
+        p=pathlib.Path(''README.md'')
+
+        p.write_text(p.read_text().replace(''(docs/'', ''(https://raw.githubusercontent.com/''+os.environ[''GITHUB_REPOSITORY'']+''/v''+os.environ[''VERSION'']+''/docs/''))
+
+        PY
+
+        uv build
+
+        uv run python scripts/package_smoke.py
+
+        printf ''Built from reviewed main commit %s\n'' "$GITHUB_SHA" > release-notes.md
+
+        '
+      env:
+        VERSION: ${{ needs.target.outputs.version }}
+        SETUPTOOLS_SCM_PRETEND_VERSION: ${{ needs.target.outputs.version }}
+    - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9
+      id: dist
+      with:
+        name: trusted-release
+        path: 'dist/*
+
+          release-notes.md'
+        if-no-files-found: error
+        retention-days: 7
+    name: Build
+  github-release:
+    if: github.ref == 'refs/heads/main' && github.actor == 'mikejhill' && github.triggering_actor == 'mikejhill' && needs.build.result
+      == 'success'
+    needs:
+    - target
+    - build
+    - attest
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: write # Create immutable refs and upload tested release artifacts.
+    steps:
+    - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333
+      with:
+        artifact-ids: ${{ needs.build.outputs.artifact-id }}
+        path: release
+    - name: Publish same-run artifacts from trusted merge
+      run: "# The approved immutable-v* ruleset must already prohibit tag updates/deletion.\nancestor=$(gh api \"repos/$GITHUB_REPOSITORY/compare/$GITHUB_SHA...main\"\
+        \ --jq .merge_base_commit.sha)\ntest \"$ancestor\" = \"$GITHUB_SHA\" || { echo 'Release commit is no longer on main.'\
+        \ >&2; exit 1; }\npython3 - <<'PY'\nimport json,os,pathlib,re\nassert re.fullmatch(r'v[0-9]+\\.[0-9]+\\.[0-9]+',os.environ['TAG'])\n\
+        assert re.fullmatch(r'[0-9a-f]{40}',os.environ['GITHUB_SHA'])\npathlib.Path('release-ref.json').write_text(json.dumps({'ref':'refs/tags/'+os.environ['TAG'],'sha':os.environ['GITHUB_SHA']}))\n\
+        PY\n# Ref creation is atomic: if another process created it first, accept only the same commit.\nif ! gh api --method\
+        \ POST \"repos/$GITHUB_REPOSITORY/git/refs\" --input release-ref.json >/dev/null 2>tag-create-error.txt; then\n  actual=$(gh\
+        \ api \"repos/$GITHUB_REPOSITORY/commits/$TAG\" --jq .sha)\n  test \"$actual\" = \"$GITHUB_SHA\" || { echo 'Tag creation\
+        \ failed or a conflicting tag exists.' >&2; exit 1; }\nfi\nactual=$(gh api \"repos/$GITHUB_REPOSITORY/commits/$TAG\"\
+        \ --jq .sha)\ntest \"$actual\" = \"$GITHUB_SHA\" || { echo 'Tag does not match the trusted merge.' >&2; exit 1; }\n\
+        if gh release view \"$TAG\" --repo \"$GITHUB_REPOSITORY\" >/dev/null 2>&1; then\n  :\nelse\n  gh release create \"\
+        $TAG\" --repo \"$GITHUB_REPOSITORY\" --verify-tag --title \"$TAG\" --generate-notes --notes-file release/release-notes.md\n\
+        fi\ngh release upload \"$TAG\" release/dist/* --repo \"$GITHUB_REPOSITORY\" --clobber\n"
+      env:
+        GH_TOKEN: ${{ github.token }}
+        TAG: v${{ needs.target.outputs.version }}
+    name: Github Release
+  pypi:
+    if: github.ref == 'refs/heads/main' && github.actor == 'mikejhill' && github.triggering_actor == 'mikejhill' && needs.github-release.result
+      == 'success'
+    needs:
+    - target
+    - build
+    - github-release
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    environment: pypi
+    permissions:
+      id-token: write # OIDC identity for attestation or trusted PyPI publishing.
+    steps:
+    - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333
+      with:
+        artifact-ids: ${{ needs.build.outputs.artifact-id }}
+        path: release
+    - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086
+      with:
+        packages-dir: release/dist/
+        skip-existing: true
+    name: Pypi
+  attest:
+    name: Attest tested artifacts
+    needs: build
+    if: github.ref == 'refs/heads/main' && github.actor == 'mikejhill' && github.triggering_actor == 'mikejhill' && needs.build.result
+      == 'success'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      id-token: write # OIDC identity for attestation or trusted PyPI publishing.
+      attestations: write # Store provenance for these same-run build artifacts.
+    steps:
+    - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333
+      with:
+        path: release
+        artifact-ids: ${{ needs.build.outputs.artifact-id }}
+    - uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6
+      with:
+        subject-path: release/dist/*

{launchline-0.2.1.dev0 → launchline-0.4.0}/.gitignore

@@ -257,3 +257,10 @@ __marimo__/
 
 # hatch-vcs generated version file
 src/launchline/_version.py
+
+junit.xml
+release/
+
+.semrel/
+.version
+release-changelog.md

{launchline-0.2.1.dev0 → launchline-0.4.0}/.markdownlint.json

@@ -1,4 +1,5 @@
 {
   "MD013": false,
+  "MD024": { "siblings_only": true },
   "MD033": false
 }

launchline-0.4.0/.semrelrc

@@ -0,0 +1,21 @@
+{
+  "plugins": {
+    "provider": {
+      "name": "github@1.19.0"
+    },
+    "commit-analyzer": {
+      "name": "default@1.15.0"
+    },
+    "changelog-generator": {
+      "name": "default@1.15.0"
+    },
+    "ci-condition": {
+      "name": "default@1.11.0"
+    },
+    "files-updater": {
+      "names": [
+        "npm@1.11.0"
+      ]
+    }
+  }
+}

{launchline-0.2.1.dev0 → launchline-0.4.0}/CHANGELOG.md

@@ -7,11 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Menus
+
+- Add nested menus with Back navigation, lazy JSON providers, explicit refresh/retry,
+  configurable parent refresh, and stable selection restoration.
+- Bound generated output, provider timeouts and process cleanup; cache up to 128 menu
+  snapshots with inactive least-recently-used eviction. Existing static configs remain valid.
+- Add shared declaration fixtures, actual provider/terminal tests and seeded menu mutations.
+  See [menu lifecycle and provider contract](docs/menus.md) for examples and limits.
+
+### Removed
+
+- Reverted array syntax for `command` config key; `command` is string-only,
+  use `args` for arguments
+
+### Changed
+
+- Improved test naming to follow `[unit]_[scenario]_[expectedResult]` pattern
+- Added diagnostic failure messages to all test assertions
+- Release workflow now supports `force-patch` input for non-bumping commits
+
+## [0.2.0] - 2026-03-30
+
 ### Added
 
-- `command` config key now accepts a list of strings (e.g.,
-  `command = ["ssh", "-t", "my server"]`) for easier argument handling,
-  especially with values containing spaces
 - `--config-path` CLI flag to print the active configuration file path
 
 ### Fixed
@@ -19,6 +38,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - PyPI package page now renders README images correctly (paths are rewritten
   to absolute URLs during the release build)
 - Release artifacts no longer accidentally include non-distribution files
+- Release workflow now produces correct version numbers (fixed dirty-tree
+  version detection via `SETUPTOOLS_SCM_PRETEND_VERSION`)
 
 ## [0.1.0] - 2026-03-30
 

{launchline-0.2.1.dev0 → launchline-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: launchline
-Version: 0.2.1.dev0
+Version: 0.4.0
 Summary: A lightweight terminal launcher for interactive CLI tools.
 Project-URL: Homepage, https://github.com/mikejhill/launchline
 Project-URL: Repository, https://github.com/mikejhill/launchline
@@ -24,12 +24,14 @@ Description-Content-Type: text/markdown
 
 [![CI](https://github.com/mikejhill/launchline/actions/workflows/ci.yml/badge.svg)](https://github.com/mikejhill/launchline/actions/workflows/ci.yml)
 [![Release](https://github.com/mikejhill/launchline/actions/workflows/release.yml/badge.svg)](https://github.com/mikejhill/launchline/actions/workflows/release.yml)
+[![PyPI](https://img.shields.io/pypi/v/launchline)](https://pypi.org/project/launchline/)
+[![Python](https://img.shields.io/pypi/pyversions/launchline)](https://pypi.org/project/launchline/)
 
 A lightweight terminal launcher for interactive CLI tools. Define your frequently
 used commands in a TOML config file, then pick them from a fuzzy-searchable menu
 instead of remembering flags and paths.
 
-![LaunchLine demo](https://raw.githubusercontent.com/mikejhill/launchline/v0.2.0/docs/images/demo.gif)
+![LaunchLine demo](https://raw.githubusercontent.com/mikejhill/launchline/v0.4.0/docs/images/demo.gif)
 
 ## Why
 
@@ -50,7 +52,7 @@ instead.
 
 |           Fuzzy search            |         Arrow-key navigation          |
 | :-------------------------------: | :-----------------------------------: |
-| ![Search](https://raw.githubusercontent.com/mikejhill/launchline/v0.2.0/docs/images/search.png) | ![Navigate](https://raw.githubusercontent.com/mikejhill/launchline/v0.2.0/docs/images/navigate.png) |
+| ![Search](https://raw.githubusercontent.com/mikejhill/launchline/v0.4.0/docs/images/search.png) | ![Navigate](https://raw.githubusercontent.com/mikejhill/launchline/v0.4.0/docs/images/navigate.png) |
 
 ## Installation
 
@@ -118,29 +120,29 @@ Config file format is [TOML](https://toml.io). The file has an optional
 | `clear_on_launch` | bool   | `true`         | Clear terminal before launching an entry                          |
 | `ghost_text`      | bool   | `true`         | Show the highlighted entry name as an autocomplete hint on prompt |
 | `numeric_trigger` | bool   | `true`         | Pressing a digit immediately launches the matching entry          |
+| `refresh_on_return` | boolean | `false` | Regenerate a dynamic root after returning from a submenu |
 
 ### `[[entries]]`
 
 Each `[[entries]]` table defines one launchable tool:
 
-| Key                 | Type                      | Required | Default | Description                                                    |
-| ------------------- | ------------------------- | -------- | ------- | -------------------------------------------------------------- |
-| `name`              | string                    | yes      | —       | Display name shown in the menu                                 |
-| `command`           | string or list of strings | yes      | —       | Executable to run (with optional inline arguments)             |
-| `args`              | list of strings           | no       | `[]`    | Additional arguments appended after any inline command args    |
-| `description`       | string                    | no       | `""`    | Short description shown next to the name                       |
-| `working_directory` | string                    | no       | —       | Working directory for the subprocess                           |
-| `env`               | table                     | no       | `{}`    | Extra environment variables (`KEY = "value"`)                  |
+| Key                 | Type            | Required | Default | Description                                                    |
+| ------------------- | --------------- | -------- | ------- | -------------------------------------------------------------- |
+| `name`              | string          | yes      | —       | Display name shown in the menu                                 |
+| `command`           | string          | yes      | —       | Executable to run                                              |
+| `args`              | list of strings | no       | `[]`    | Arguments passed to the command                                |
+| `description`       | string          | no       | `""`    | Short description shown next to the name                       |
+| `working_directory` | string          | no       | —       | Working directory for the subprocess                           |
+| `env`               | table           | no       | `{}`    | Extra environment variables (`KEY = "value"`)                  |
+| `id` | string | no | `""` | Stable per-menu identity for refreshed selection |
+| `menu` | table | no | - | Submenu declaration, exclusive with command fields |
 
 ### Validation Rules
 
-- At least one `[[entries]]` table is required.
-- Every entry must have both `name` and `command`.
-- `command` may be a string (`"pwsh"`) or a list (`["ssh", "-t", "host"]`).
-  When a list, the first element is the executable and the rest are arguments.
+- A root requires nonempty `[[entries]]` or a `[provider]` declaration.
+- Every entry needs `name` and either `command` or `menu`.
 - `on_exit` must be `"restart"` or `"exit"`.
-- `args` must be a list (not a bare string). These are appended after any
-  arguments provided inline in a `command` list.
+- `args` must be a list (not a bare string).
 - `env` must be a TOML table (not a string or list).
 - If `working_directory` does not exist at load time, it is silently reset to
   `None` (a warning is logged).
@@ -171,10 +173,6 @@ name = "PowerShell"
 command = "pwsh"
 args = ["-NoProfile"]
 env = { TERM = "xterm-256color" }
-
-[[entries]]
-name = "Remote Server"
-command = ["ssh", "-t", "my server", "bash"]
 ```
 
 ## Usage
@@ -220,3 +218,30 @@ uv run mypy src
 ## License
 
 MIT
+
+## See Also
+
+- **[LaunchLine (Rust)](https://github.com/mikejhill/launchline-rust)** — a Rust
+  implementation with the shared configuration and keyboard contract,
+  ships as a single native binary.
+
+## Compatibility and validation
+
+Use `launchline --check-config` to validate configuration without opening the menu.
+Set `NO_COLOR` for a selection marker without ANSI color. See the
+[compatibility matrix](https://raw.githubusercontent.com/mikejhill/launchline/v0.4.0/docs/compatibility.md), [reproducible test and performance
+results](https://raw.githubusercontent.com/mikejhill/launchline/v0.4.0/docs/validation/report.md), and [release readiness](https://raw.githubusercontent.com/mikejhill/launchline/v0.4.0/docs/releasing.md).
+
+### `[provider]`
+
+The same table is accepted under `entries.menu.provider`. See the
+[menu lifecycle and provider contract](https://raw.githubusercontent.com/mikejhill/launchline/v0.4.0/docs/menus.md) for nesting, caching,
+refresh/back behavior, limits, errors and examples.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `command` | string | required | Explicit trusted provider executable |
+| `args` | string array | `[]` | Literal argv |
+| `env` | string table | `{}` | Environment overlay |
+| `working_directory` | string | inherited | Provider working directory |
+| `timeout_seconds` | integer | `10` | Deadline from 1 to 300 seconds |

{launchline-0.2.1.dev0 → launchline-0.4.0}/README.md

@@ -2,12 +2,14 @@
 
 [![CI](https://github.com/mikejhill/launchline/actions/workflows/ci.yml/badge.svg)](https://github.com/mikejhill/launchline/actions/workflows/ci.yml)
 [![Release](https://github.com/mikejhill/launchline/actions/workflows/release.yml/badge.svg)](https://github.com/mikejhill/launchline/actions/workflows/release.yml)
+[![PyPI](https://img.shields.io/pypi/v/launchline)](https://pypi.org/project/launchline/)
+[![Python](https://img.shields.io/pypi/pyversions/launchline)](https://pypi.org/project/launchline/)
 
 A lightweight terminal launcher for interactive CLI tools. Define your frequently
 used commands in a TOML config file, then pick them from a fuzzy-searchable menu
 instead of remembering flags and paths.
 
-![LaunchLine demo](https://raw.githubusercontent.com/mikejhill/launchline/v0.2.0/docs/images/demo.gif)
+![LaunchLine demo](https://raw.githubusercontent.com/mikejhill/launchline/v0.4.0/docs/images/demo.gif)
 
 ## Why
 
@@ -28,7 +30,7 @@ instead.
 
 |           Fuzzy search            |         Arrow-key navigation          |
 | :-------------------------------: | :-----------------------------------: |
-| ![Search](https://raw.githubusercontent.com/mikejhill/launchline/v0.2.0/docs/images/search.png) | ![Navigate](https://raw.githubusercontent.com/mikejhill/launchline/v0.2.0/docs/images/navigate.png) |
+| ![Search](https://raw.githubusercontent.com/mikejhill/launchline/v0.4.0/docs/images/search.png) | ![Navigate](https://raw.githubusercontent.com/mikejhill/launchline/v0.4.0/docs/images/navigate.png) |
 
 ## Installation
 
@@ -96,29 +98,29 @@ Config file format is [TOML](https://toml.io). The file has an optional
 | `clear_on_launch` | bool   | `true`         | Clear terminal before launching an entry                          |
 | `ghost_text`      | bool   | `true`         | Show the highlighted entry name as an autocomplete hint on prompt |
 | `numeric_trigger` | bool   | `true`         | Pressing a digit immediately launches the matching entry          |
+| `refresh_on_return` | boolean | `false` | Regenerate a dynamic root after returning from a submenu |
 
 ### `[[entries]]`
 
 Each `[[entries]]` table defines one launchable tool:
 
-| Key                 | Type                      | Required | Default | Description                                                    |
-| ------------------- | ------------------------- | -------- | ------- | -------------------------------------------------------------- |
-| `name`              | string                    | yes      | —       | Display name shown in the menu                                 |
-| `command`           | string or list of strings | yes      | —       | Executable to run (with optional inline arguments)             |
-| `args`              | list of strings           | no       | `[]`    | Additional arguments appended after any inline command args    |
-| `description`       | string                    | no       | `""`    | Short description shown next to the name                       |
-| `working_directory` | string                    | no       | —       | Working directory for the subprocess                           |
-| `env`               | table                     | no       | `{}`    | Extra environment variables (`KEY = "value"`)                  |
+| Key                 | Type            | Required | Default | Description                                                    |
+| ------------------- | --------------- | -------- | ------- | -------------------------------------------------------------- |
+| `name`              | string          | yes      | —       | Display name shown in the menu                                 |
+| `command`           | string          | yes      | —       | Executable to run                                              |
+| `args`              | list of strings | no       | `[]`    | Arguments passed to the command                                |
+| `description`       | string          | no       | `""`    | Short description shown next to the name                       |
+| `working_directory` | string          | no       | —       | Working directory for the subprocess                           |
+| `env`               | table           | no       | `{}`    | Extra environment variables (`KEY = "value"`)                  |
+| `id` | string | no | `""` | Stable per-menu identity for refreshed selection |
+| `menu` | table | no | - | Submenu declaration, exclusive with command fields |
 
 ### Validation Rules
 
-- At least one `[[entries]]` table is required.
-- Every entry must have both `name` and `command`.
-- `command` may be a string (`"pwsh"`) or a list (`["ssh", "-t", "host"]`).
-  When a list, the first element is the executable and the rest are arguments.
+- A root requires nonempty `[[entries]]` or a `[provider]` declaration.
+- Every entry needs `name` and either `command` or `menu`.
 - `on_exit` must be `"restart"` or `"exit"`.
-- `args` must be a list (not a bare string). These are appended after any
-  arguments provided inline in a `command` list.
+- `args` must be a list (not a bare string).
 - `env` must be a TOML table (not a string or list).
 - If `working_directory` does not exist at load time, it is silently reset to
   `None` (a warning is logged).
@@ -149,10 +151,6 @@ name = "PowerShell"
 command = "pwsh"
 args = ["-NoProfile"]
 env = { TERM = "xterm-256color" }
-
-[[entries]]
-name = "Remote Server"
-command = ["ssh", "-t", "my server", "bash"]
 ```
 
 ## Usage
@@ -198,3 +196,30 @@ uv run mypy src
 ## License
 
 MIT
+
+## See Also
+
+- **[LaunchLine (Rust)](https://github.com/mikejhill/launchline-rust)** — a Rust
+  implementation with the shared configuration and keyboard contract,
+  ships as a single native binary.
+
+## Compatibility and validation
+
+Use `launchline --check-config` to validate configuration without opening the menu.
+Set `NO_COLOR` for a selection marker without ANSI color. See the
+[compatibility matrix](https://raw.githubusercontent.com/mikejhill/launchline/v0.4.0/docs/compatibility.md), [reproducible test and performance
+results](https://raw.githubusercontent.com/mikejhill/launchline/v0.4.0/docs/validation/report.md), and [release readiness](https://raw.githubusercontent.com/mikejhill/launchline/v0.4.0/docs/releasing.md).
+
+### `[provider]`
+
+The same table is accepted under `entries.menu.provider`. See the
+[menu lifecycle and provider contract](https://raw.githubusercontent.com/mikejhill/launchline/v0.4.0/docs/menus.md) for nesting, caching,
+refresh/back behavior, limits, errors and examples.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `command` | string | required | Explicit trusted provider executable |
+| `args` | string array | `[]` | Literal argv |
+| `env` | string table | `{}` | Environment overlay |
+| `working_directory` | string | inherited | Provider working directory |
+| `timeout_seconds` | integer | `10` | Deadline from 1 to 300 seconds |

launchline-0.4.0/docs/compatibility.md

@@ -0,0 +1,39 @@
+# Shared compatibility contract
+
+Baseline: Python `904ace1`, Rust `109a68b`. Modernized together on MHILL-LAPTOP.
+This matrix records the supported contract and evidence, not universal parity.
+
+| Surface | Baseline gap | Implemented contract | Evidence |
+| --- | --- | --- | --- |
+| Configuration | Python coerced types; Rust discarded invalid args/env | Strict strings, booleans, string arrays/maps; reject controls/NUL and illegal environment keys | Both unit suites; 15 differential real CLI cases in validation/parity.json |
+| Resolution | Same CLI > LAUNCHLINE_CONFIG > default precedence | Explicit missing paths fail; exclusive default creation; missing/file cwd warns and inherits | Config tests; actual CLI and child processes |
+| Search | Equivalent greedy subsequence scoring | Identical score bonuses and stable ties; monotonic search avoids tail scans | Shared 405-case ASCII/Unicode score corpus; paired benchmarks |
+| Numeric selection | Python non-ASCII digit crash | ASCII digits only, existing prefix and shortcut semantics | Keyboard and mutation tests |
+| Editing | Rust UTF-8 byte cursor could panic | Character boundary editing; Emacs keys, arrows, Escape clear/quit | Rust unit UX; Python decoder/UI tests; real PTY flows |
+| CLI | Rust accepted arbitrary log levels; Python config-path tracebacks | Same five uppercase levels; friendly failures; --check-config validates without opening TUI; non-TTY guard | Actual subprocess and wheel smoke tests |
+| Launch | Rust cloned entire environment; POSIX status representation differed | Literal argv, inherited env plus overlay, cwd, child exit code; interrupted child 130; POSIX signal 128+signal | Actual child probe; Python Linux SIGTERM test; Rust Unix test added but not run locally |
+| Terminal | Windows inherited ignore flag; Unix queued input loss | Enable own Ctrl+C; restore terminal; preserve queued UTF-8 input; stop on EOF/read error | Windows PTY both; Linux PTY Python; faithful OS-boundary simulations |
+| Accessibility | Color-only emphasis | NO_COLOR suppresses SGR with visible selection marker; keyboard navigation and resize | PTY output/assertions both; no screen-reader certification |
+| Distribution | Rust archives lacked icons; wrapper used wrong version metadata | Bundle icons; wrapper uses launchline-rust version, verifies SHA256SUMS before atomic cache install | Built native archive and isolated installed wheel; tamper/interruption tests |
+| Release | Python #1 pending; Rust broad permissions | Preserve #1 pin/generated notes; owner + rerun owner gates, exact SHA, read-only build, isolated publishers, provenance | actionlint, zizmor auditor, mocked actual publisher body, no-remote semantic-release fixture |
+
+Unknown TOML keys remain ignored for compatibility. Shell expansion is not supported.
+Portable home expansion is `~`/`~/...`; Python also recognizes OS-supported named-user
+forms. Diagnostic wording, argparse/clap help formatting, platform process lookup,
+batch execution, Unicode database versions, terminal escape timing and font widths
+can differ. Cursor accounting uses code points rather than grapheme/display columns;
+wide/combining glyph layout is not claimed equivalent. Python needs CPython >=3.12;
+Rust is native, with a separate Python >=3.9 download wrapper. Binary and interpreter
+startup/memory costs therefore differ. No maximum-performance claim is made.
+
+Executed: Windows x64 both; Ubuntu/WSL Python. macOS, ARM targets, Rust Linux/macOS,
+physical terminal/screen-reader combinations and hosted CI have not been executed
+here. See [validation report](validation/report.md) and [release readiness](releasing.md).
+
+## Nested and dynamic menu extension
+
+See the [shared lifecycle and provider schema](menus.md) and
+[feature validation matrix](validation/menu-checkpoint.md) for current evidence.
+The earlier matrix above describes the modernization baseline; feature-head hosted
+CI and ordered releases are tracked separately. Windows raw/Kitty input differences
+are explicitly documented rather than asserted equivalent.