CLI distribution verification requirements
These requirements track the live implementation of the CLI distribution verification specification.
| ID | Requirement | Implementation | Verification | Documentation | Evidence |
|---|---|---|---|---|---|
| CLIDIST-001 | The shipped bundled-Python runtime and config-specific optimized PyInstaller bundle remain distinct distributions with separate plugin policies and test suites. | Implemented | Automated | Documented | Runtime-layout and frozen dynamic-install tests; current implementation |
| CLIDIST-010 | The source-installation smoke boots the default config from a fresh lean Core/application venv and clean files, dynamically installing default path: plugins into the clean config-owned cache. |
Implemented | Automated | Documented | application/python/scripts/smoke_source_install.py; npm run test:cli:source-install passed on macOS ARM64 |
| CLIDIST-020 | The extracted-archive smoke independently unpacks a current-platform shipped archive, executes its launcher directly, boots a default-derived config, and dynamically installs a designated packaged plugin that is absent from the preinstalled manifest into a fresh user cache. | Implemented | Automated | Documented | application/python/scripts/smoke_runtime_archive.py; all native targets passed after path migration in run 34455407631 |
| CLIDIST-030 | The default-installer smoke independently runs the public download installer with its default install root, command name, and automatic PATH-directory selection; it invokes crystal-lattice by name, boots a default-derived config, and dynamically installs the designated non-preinstalled packaged plugin into its own fresh cache. |
Implemented | Automated | Documented | application/python/scripts/smoke_default_install.py; all native targets passed after path migration in run 34455407631 |
| CLIDIST-040 | Root npm commands independently run the source-installation, extracted-archive, and default-installer acceptance scenarios through the same direct scenario entry points used by CI. | Implemented | Automated | Documented | package.json; application/python/scripts/run_distribution_smoke.py; exact package-script tests; all three migrated root commands passed |
| CLIDIST-050 | Every native release-matrix target runs both the extracted-archive and default-installer root npm commands against the one archive built by that target. | Implemented | Automated | Documented | Separate package-local npm steps passed on Linux AMD64, macOS AMD64/ARM64, and Windows AMD64 in run 34455407631 |
| CLIDIST-051 | The extracted-archive and default-installer smokes share no mutable home, workspace, config directory, plugin cache, pip cache, installation directory, or command directory; neither smoke invokes or depends on the other, and each can produce its own result after archive construction succeeds. | Implemented | Automated | Documented | Standalone scenario scripts create independent temporary roots; both root commands passed concurrently against one immutable archive |
| CLIDIST-052 | Each archive-based smoke begins with no plugin-installation state, verifies that its designated probe plugin is not listed as preinstalled, triggers a real installation through the packaged runtime, and asserts plugin-specific installation metadata in that smoke's cache. | Implemented | Automated | Documented | Both archive-based npm smokes independently installed generic-callback-app; focused helper tests cover config and cache assertions |
| CLIDIST-060 | A new default config starts and exposes all configured agents when its external ${env:...} values are absent from the process and discovered .env files. |
Implemented | Automated | Documented | Shared boot helper plus source-installation, extracted-archive, and installed-command smokes passed; configuration guide |
| CLIDIST-061 | Normal CLI use does not require shell exports: the CLI loads credentials from documented config, project, user, and discovered .env files without mutating the process environment. |
Implemented | Automated | Documented | test_cli_environment_isolation.py; test_application_layer_config.py; placeholder guide |
| CLIDIST-062 | Distribution startup performs no provider/tool API request, synthesizes no credential, and leaves request authentication to the selected provider or tool contract. | Implemented | Automated | Documented | Shared boot helper calls only local readiness and agent-list endpoints; all three delivered smoke paths passed without dummy values |
| CLIDIST-063 | The config loader classifies each unresolved ${env:...} reference as a nonfatal env_missing warning with its variable and config path; independently invalid resolved structures retain their normal fatal validation. |
Implemented | Automated | Documented | agent_app.config.resolve_placeholders; test_config_env_substitution.py; test_application_config_errors.py; placeholder guide |
| CLIDIST-070 | Archive construction completes in an isolated build environment before archive-consuming tests start and cannot install or upgrade packages in the repository test environment. | Implemented | Automated | Documented | application/python/scripts/build_runtime_archive.py uses a temporary host venv; migrated fresh build passed and the earlier environment hash evidence remains recorded in the task |
| CLIDIST-071 | The default local archive build provisions an uv-managed Python 3.11 runtime equivalent to the release runtime family; explicit runtime and prebuilt-archive overrides remain optional. |
Implemented | Automated | Documented | Nox-free build provisioned managed CPython 3.11.16; archive portability and both archive-based smokes passed |
| CLIDIST-072 | Boot-probe cleanup owns the full process tree on POSIX and Windows, applies bounded graceful and forced termination, and verifies that the server port closes. | Implemented | Automated | Documented | POSIX helper coverage plus direct archive and outer installed .cmd cleanup on native Windows in run 34372198266 |
| CLIDIST-080 | Without an explicit bin-directory override, the public installer selects an existing suitable writable directory already present on PATH and installs the crystal-lattice command there, making it resolvable by name immediately in the supported terminal environment. |
Implemented | Automated | Documented | Public-installer smoke resolved and booted by name on all native targets in run 34372198266; focused selection tests |
| CLIDIST-081 | Default bin-directory selection is deterministic, prefers an existing installation and conventional user command directories, rejects unsafe or unusable PATH entries, and fails before installation with an actionable message when no suitable PATH directory exists; an explicit override remains supported. | Implemented | Automated | Documented | Installer tests cover preferred selection, incompatible existing command avoidance, explicit override, local archive input, and no-candidate failure |
| CLIDIST-090 | Specifications, current documentation, commands, tests, and diagnostics use descriptive scenario and component names; any retained historical “level” terminology is introduced with its meaning rather than assumed. | Implemented | Automated | Documented | Scoped npm commands, shortened package-local scripts, focused search, and current/specification documentation |
| CLIDIST-091 | Distribution acceptance orchestration has one direct implementation per scenario; local npm commands and GitHub Actions call those same entry points, while shared code is limited to lower-level build, extraction, configuration, boot, and process-cleanup helpers that cannot substitute one scenario for another. | Implemented | Automated | Documented | Package-local standalone scenario scripts, package/workflow contract tests, removed pytest scenario file, Nox, and duplicate Python production installer |
| CLIDIST-100 | Application-only CLI build, install, version, distribution-smoke, and smoke-support entry points live under application/python/scripts/; root scripts/ retains repository-wide utilities and the documented cross-runtime packaging primitive cluster. |
Implemented | Automated | Documented | test_application_owned_cli_scripts_are_package_local; application scripts README and current implementation page |
| CLIDIST-101 | Package-local maintainer scripts and generated application caches are not copied wholesale into bundled-Python runtime application trees or Python distributions; the runtime archive retains only its explicitly staged internal build scripts. | Implemented | Automated | Documented | Runtime-package staging exclusion and archive-layout tests; setuptools package-discovery test |
| CLIDIST-102 | Root CLI build and install npm commands use the action:cli:variant convention consistently with test:cli:* and release:cli:*, and tracked consumers use the scoped names without obsolete aliases. |
Implemented | Automated | Documented | Exact package-script and VS Code task tests; all four renamed commands passed locally; native smoke npm commands passed in run 34455407631 |
| CLIDIST-103 | Every potentially long CLI environment-creation, dependency-installation, build, installation, smoke, or boot phase prints numbered progress before work begins; human-readable child output remains visible, boot waits identify the server log and periodically report status, and failure diagnostics remain bounded. | Implemented | Automated | Documented | test_cli_script_progress.py; installer progress test; local source/build/install/smoke logs; native archive and installer logs in run 34455407631 |
| CLIDIST-110 | Bundled-Python releases contain natively built and verified archives for macOS AMD64, macOS ARM64, Linux AMD64, Linux ARM64, Windows AMD64, and Windows ARM64; emulated-only execution does not establish support. | Implemented | Automated | Documented | All six native targets passed in runs 34756416576 and 34860183022; installation overview and platform/manual guides |
| CLIDIST-111 | The public Bash installer selects the correct AMD64 or ARM64 archive on macOS and Linux, preserves the supported Windows Git Bash path, and retains staging, command discovery, overrides, verification, and progress behavior. | Implemented | Automated | Documented | Native Bash matrix coverage in run 34860183022 and macOS/Linux plus Windows installation guides |
| CLIDIST-112 | A standalone public PowerShell installer installs the Windows AMD64 or ARM64 archive without Git Bash, WSL, Python, administrator privileges, or exported variables and verifies the installed runtime. | Implemented | Automated | Documented | Exact irm ... | iex path passed Windows AMD64 and ARM64 in run 34860183022; Windows installation guide |
| CLIDIST-113 | Native Windows installation reuses the suitable writable PATH directory of an existing bundled-Python command and otherwise creates a conventional per-user command directory, adds it once to user PATH and the current PowerShell process, and makes crystal-lattice resolvable from PowerShell and a fresh cmd.exe. |
Implemented | Automated | Documented | Windows AMD64/ARM64 PATH and command-discovery checks passed in run 34860183022; Windows guide |
| CLIDIST-114 | Direct archive use, Bash installation, and PowerShell installation have independent user-path acceptance implementations and mutable state; every applicable native release target runs the relevant root npm scenarios against its built archive. | Implemented | Automated | Documented | All six targets passed applicable scenarios in run 34860183022; current CLI-distribution implementation guide |
| CLIDIST-115 | Users can select the correct immutable release archive for every supported target, extract it, run its platform launcher directly, and optionally install a command without depending on either public installer. | Implemented | Automated | Documented | Direct archive use passed on all six targets in run 34860183022; manual installation guide |
| CLIDIST-116 | Release publication validates and publishes install.sh, install.ps1, latest.txt, and all six native archives, then performs bounded post-CDN public endpoint and installation checks that do not rely only on pre-publication loopback servers. |
Implemented | Automated | Documented | v0.1.5 release run 34878990045; production download smoke passed on 2026-09-14 |
Current-state note
Requirements CLIDIST-001 through CLIDIST-103 have local automated evidence.
Requirements CLIDIST-110 through CLIDIST-116 define the approved
cross-platform installation target and are in progress. The existing
package-local
extracted-archive and default-installer npm smokes also pass independently on
Linux AMD64, macOS AMD64, macOS ARM64, and Windows AMD64 in
run 34455407631.