Skip to content

feat: add standalone CLI installation#209

Merged
DeadWaveWave merged 6 commits intomainfrom
feat/cli-installation
Apr 30, 2026
Merged

feat: add standalone CLI installation#209
DeadWaveWave merged 6 commits intomainfrom
feat/cli-installation

Conversation

@DeadWaveWave
Copy link
Copy Markdown
Owner

💡 Change Scope

  • Small Change: Fast feedback, localized UI/logic, low-risk.
  • Large Change: New feature, cross-boundary logic, runtime-risk (persistence, IPC, lifecycle, recovery).

📝 What Does This PR Do?

Adds two supported OpenCove CLI installation paths and makes the packaged CLI runtime self-contained:

  • Repairs Desktop Settings → Worker → CLI → Install CLI so packaged installs write runtime-backed launchers instead of repo-path launchers.
  • Adds standalone release assets for macOS/Linux/Windows so users can install opencove without Desktop and run Worker/Web UI on servers.
  • Adds install/uninstall scripts for standalone runtime, including Windows PowerShell support and opencove.cmd PATH setup.
  • Adds release workflow smoke coverage for standalone asset → installer → launcher → opencove worker start --help.
  • Adds launcher owner metadata so Desktop and standalone installs can coexist or overwrite safely, while uninstall only removes the launcher owned by that install path.
  • Updates README, README_ZH, CLI docs, release docs, and the implementation spec with the supported lifecycle boundaries.

🏗️ Large Change Spec (Required if "Large Change" is checked)

1. Context & Business Logic

Users need a reliable opencove CLI both from Desktop and on machines without Desktop. The release pipeline now publishes standalone server runtime bundles, and the installers generate a stable launcher that runs the packaged CLI via Electron-as-Node. Desktop install keeps the app-owned launcher flow, while standalone install supports server deployment for Worker/Web UI.

2. State Ownership & Invariants

State owners:

  • Release pipeline owns standalone runtime bundle contents, naming, and upload.
  • Desktop installer owns Desktop-managed launcher metadata and PATH integration.
  • Standalone installer owns standalone runtime files and standalone-managed launcher metadata.
  • Worker remains the durable truth owner; CLI stays a client and does not bypass the Control Surface.

Invariants:

  • Packaged CLI/Worker launchers resolve entrypoints from the installed runtime, not a repo checkout.
  • Install paths may overwrite an OpenCove-owned launcher, but uninstall only removes a launcher owned by that install path and refuses non-OpenCove launchers.
  • Standalone uninstall removes runtime bundles and launcher ownership only; it must not remove userData, DB, or Desktop-owned launchers.

3. Verification Plan & Regression Layer

Regression layers covered:

  • Unit: tests/unit/app/cliPathInstaller.spec.ts covers Desktop launcher generation/repair and Windows standalone launcher owner isolation.
  • Script syntax: sh -n scripts/release-assets/opencove-install.sh && sh -n scripts/release-assets/opencove-uninstall.sh passed locally.
  • Release workflow: standalone install smoke is wired for macOS/Linux and Windows in GitHub Actions.
  • Full local gate: pnpm pre-commit passed with 204 passed, 45 skipped E2E results. Skipped cases are unrelated flaky E2E tests explicitly deferred from this CLI installation task.

✅ Delivery & Compliance Checklist

  • My code passes the ultimate gatekeeper: pnpm pre-commit is completely green.
  • I have signed the CLA if required (see CLA.md).
  • I have included new tests to lock down the behavior (or explicitly stated why it's untestable).
  • I have strictly adhered to the DEVELOPMENT.md architectural boundaries.
  • I have attached a screenshot or screen recording (if this touches the UI). N/A: no UI surface changed.
  • I have updated the documentation accordingly (if adding a feature or changing a contract).

📸 Screenshots / Visual Evidence

N/A: this change is installer, release, CLI runtime, and docs work; no visual UI change.

@DeadWaveWave DeadWaveWave merged commit 2610a03 into main Apr 30, 2026
7 checks passed
@DeadWaveWave DeadWaveWave deleted the feat/cli-installation branch April 30, 2026 09:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant