From 49680f6cbbcf06fb829333fc05b0f8d1f3aba475 Mon Sep 17 00:00:00 2001 From: pixelcola Date: Tue, 12 May 2026 15:50:55 +0800 Subject: [PATCH 1/3] docs: add installation instructions --- README.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/README.md b/README.md index bd9c6f0..c41a8cd 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,32 @@ Windows CLI for installing and controlling the `sing-box` Windows service. `sing-box.exe` and `nssm.exe` must be available in `PATH`. `sing install --bin ` can use a custom `sing-box.exe` path. +On Windows, install the runtime executables with Scoop: + +```powershell +scoop install sing-box nssm +``` + +## Installation + +Install `sing-cli`: + +```powershell +uv tool install sing-cli +``` + +Update `sing-cli`: + +```powershell +uv tool upgrade sing-cli +``` + +Uninstall `sing-cli`: + +```powershell +uv tool uninstall sing-cli +``` + ## Commands | Command | Description | From c072271ec536a08fb1902e54d337dcc0ec354ced Mon Sep 17 00:00:00 2001 From: pixelcola Date: Tue, 12 May 2026 15:52:55 +0800 Subject: [PATCH 2/3] chore(task): archive readme install uv tool --- .../05-12-readme-install-uv-tool/check.jsonl | 2 + .../implement.jsonl | 2 + .../05-12-readme-install-uv-tool/prd.md | 55 +++++++++++++++++++ .../research/uv-tool-commands.md | 14 +++++ .../05-12-readme-install-uv-tool/task.json | 26 +++++++++ 5 files changed, 99 insertions(+) create mode 100644 .trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/check.jsonl create mode 100644 .trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/implement.jsonl create mode 100644 .trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/prd.md create mode 100644 .trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/research/uv-tool-commands.md create mode 100644 .trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/task.json diff --git a/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/check.jsonl b/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/check.jsonl new file mode 100644 index 0000000..04442d1 --- /dev/null +++ b/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/check.jsonl @@ -0,0 +1,2 @@ +{"file": ".trellis/spec/backend/index.md", "reason": "Verify README install docs match CLI project facts"} +{"file": ".trellis/tasks/05-12-readme-install-uv-tool/research/uv-tool-commands.md", "reason": "Verify README uses valid uv tool commands"} diff --git a/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/implement.jsonl b/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/implement.jsonl new file mode 100644 index 0000000..29bd3f9 --- /dev/null +++ b/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/implement.jsonl @@ -0,0 +1,2 @@ +{"file": ".trellis/spec/backend/index.md", "reason": "README install docs should stay aligned with CLI project facts"} +{"file": ".trellis/tasks/05-12-readme-install-uv-tool/research/uv-tool-commands.md", "reason": "Official uv tool command verification for README install docs"} diff --git a/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/prd.md b/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/prd.md new file mode 100644 index 0000000..30fc0d5 --- /dev/null +++ b/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/prd.md @@ -0,0 +1,55 @@ +# docs: update README installation instructions + +## Goal + +Update `README.md` so users can install, update, and uninstall `sing-cli` with `uv tool`, and install runtime executables with Scoop. + +## What I already know + +* The user requested README documentation for: + * `uv tool install sing-cli` + * `uv tool upgrade sing-cli` + * `uv tool uninstall sing-cli` + * `scoop install sing-box nssm` +* `README.md` currently documents runtime requirements and command usage, but not CLI installation. +* The project exposes the CLI command through `pyproject.toml` as `sing = "sing_cli.main:main"`. + +## Assumptions + +* The README should keep the existing concise structure. +* Scoop is documented as the recommended way to install `sing-box.exe` and `nssm.exe` on Windows. + +## Requirements + +* Add a README section for installing, updating, and uninstalling `sing-cli` with `uv tool`. +* Add a README example showing `scoop install sing-box nssm` for runtime dependencies. +* Preserve existing command behavior documentation. +* Keep published docs free of editor notes, migration commentary, and one-off explanatory footnotes. + +## Acceptance Criteria + +* [x] `README.md` includes `uv tool install sing-cli`. +* [x] `README.md` includes `uv tool upgrade sing-cli`. +* [x] `README.md` includes `uv tool uninstall sing-cli`. +* [x] `README.md` includes `scoop install sing-box nssm`. +* [x] The README remains visually consistent with the existing concise style. + +## Definition of Done + +* Documentation updated. +* Diff reviewed for scope. +* No code tests are required because this is a README-only change. + +## Out of Scope + +* Changing CLI behavior. +* Adding package publishing automation. +* Adding installation logic to the CLI. + +## Technical Notes + +* Relevant files inspected: + * `README.md` + * `.trellis/spec/backend/index.md` + * `uv tool --help` + * `.trellis/tasks/05-12-readme-install-uv-tool/research/uv-tool-commands.md` diff --git a/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/research/uv-tool-commands.md b/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/research/uv-tool-commands.md new file mode 100644 index 0000000..2908173 --- /dev/null +++ b/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/research/uv-tool-commands.md @@ -0,0 +1,14 @@ +# uv tool commands + +## Finding + +`uv tool` installs tools with `uv tool install`, upgrades installed tools with `uv tool upgrade`, and removes tools with `uv tool uninstall`. + +## Sources + +* Official uv guide, "Using tools": https://docs.astral.sh/uv/guides/tools/ +* Official uv CLI reference: https://docs.astral.sh/uv/reference/cli/ + +## Impact on README + +Use `uv tool upgrade sing-cli` for the update action. `uv tool update sing-cli` is not a documented `uv tool` command in the official uv CLI reference and is not present in local `uv tool --help`. diff --git a/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/task.json b/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/task.json new file mode 100644 index 0000000..8965697 --- /dev/null +++ b/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/task.json @@ -0,0 +1,26 @@ +{ + "id": "readme-install-uv-tool", + "name": "readme-install-uv-tool", + "title": "docs: update README installation instructions", + "description": "", + "status": "completed", + "dev_type": null, + "scope": null, + "package": null, + "priority": "P2", + "creator": "pixelcola", + "assignee": "pixelcola", + "createdAt": "2026-05-12", + "completedAt": "2026-05-12", + "branch": null, + "base_branch": "docs/readme-install-uv-tool", + "worktree_path": null, + "commit": null, + "pr_url": null, + "subtasks": [], + "children": [], + "parent": null, + "relatedFiles": [], + "notes": "", + "meta": {} +} \ No newline at end of file From 03694a9976388630a1e770a6d626ea7e90e0ee09 Mon Sep 17 00:00:00 2001 From: pixelcola Date: Tue, 12 May 2026 15:53:41 +0800 Subject: [PATCH 3/3] chore: record journal --- .trellis/workspace/pixelcola/index.md | 5 ++-- .trellis/workspace/pixelcola/journal-1.md | 33 +++++++++++++++++++++++ 2 files changed, 36 insertions(+), 2 deletions(-) diff --git a/.trellis/workspace/pixelcola/index.md b/.trellis/workspace/pixelcola/index.md index 4108048..97fb16d 100644 --- a/.trellis/workspace/pixelcola/index.md +++ b/.trellis/workspace/pixelcola/index.md @@ -8,7 +8,7 @@ - **Active File**: `journal-1.md` -- **Total Sessions**: 5 +- **Total Sessions**: 6 - **Last Active**: 2026-05-12 @@ -19,7 +19,7 @@ | File | Lines | Status | |------|-------|--------| -| `journal-1.md` | ~172 | Active | +| `journal-1.md` | ~205 | Active | --- @@ -29,6 +29,7 @@ | # | Date | Title | Commits | Branch | |---|------|-------|---------|--------| +| 6 | 2026-05-12 | Update README installation instructions | `49680f6` | `docs/readme-install-uv-tool` | | 5 | 2026-05-12 | Fix restart active profile | `010e59e` | `fix/restart-active-config` | | 4 | 2026-05-12 | Fix Windows subprocess output decoding | `e90a676` | `fix/windows-subprocess-output-decoding` | | 3 | 2026-05-12 | Use NSSM for Windows service | `72c1b0d` | `fix/use-nssm-service` | diff --git a/.trellis/workspace/pixelcola/journal-1.md b/.trellis/workspace/pixelcola/journal-1.md index c232414..ad58b68 100644 --- a/.trellis/workspace/pixelcola/journal-1.md +++ b/.trellis/workspace/pixelcola/journal-1.md @@ -170,3 +170,36 @@ Changed sing restart to use the active profile without accepting a profile argum ### Next Steps - None - task complete + + +## Session 6: Update README installation instructions + +**Date**: 2026-05-12 +**Task**: Update README installation instructions +**Branch**: `docs/readme-install-uv-tool` + +### Summary + +Documented Scoop runtime dependency installation and uv tool install, upgrade, and uninstall commands for sing-cli. + +### Main Changes + +(Add details) + +### Git Commits + +| Hash | Message | +|------|---------| +| `49680f6` | (see git log) | + +### Testing + +- [OK] (Add test results) + +### Status + +[OK] **Completed** + +### Next Steps + +- None - task complete