"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/
Python
fix(joplin):complement test and add lock
27494539a-hub1744a93c7674
diff --git a/README.md b/README.mdindex 4db658724..4b9f06fea 100644--- a/README.md+++ b/README.md@@ -33,7 +33,7 @@ CLI-Anything: Bridging the Gap Between AI Agents and the World's Software</stron<a href="https://github.com/HKUDS/.github/blob/main/profile/README.md"><img src="https://img.shields.io/badge/WeChat-Group-C5EAB4?style=flat&logo=wechat&logoColor=white" alt="WeChat"></a></p>-**One Command Line**: Make any software agent-ready for Pi, OpenClaw, nanobot, Cursor, Claude Code, etc. [**??����??**](README_CN.md) | [**�ձ��Z��??�����**](README_JA.md)+**One Command Line**: Make any software agent-ready for Pi, OpenClaw, nanobot, Cursor, Claude Code, etc. [**????????**](README_CN.md) | [**????Z?????????**](README_JA.md)<p align="center"><img src="assets/cli-typing.gif" alt="CLI-Anything typing demo" width="800">@@ -1162,9 +1162,9 @@ nsight-graphics 51 passed ?? (46 unit/CLI + 5 local e2e)unrealinsights 50 passed ?? (49 unit + 1 e2e, 9 backend-gated e2e skipped)cloudanalyzer 14 passed ?? (7 unit + 7 e2e)3mf 50 passed ?? (50 unit)-joplin 123 passed ?? (96 unit + 27 e2e, 1 skipped on Windows)-������������������������������������������������������������������������������������������������������������������������������������������������������������-TOTAL 2,453 passed ?? 100% pass rate+joplin 131 passed ?? (104 unit + 27 e2e, 1 skipped on Windows)+????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????+TOTAL 2,461 passed ?? 100% pass rate```---@@ -1193,65 +1193,65 @@ TOTAL 2,453 passed ?? 100% pass rate```cli-anything/-������ ? README.md # You are here-������ ? assets/ # Images and media-?? ������ icon.png # Project icon-?? ������ teaser.png # Teaser figure+?????? ? README.md # You are here+?????? ? assets/ # Images and media+?? ?????? icon.png # Project icon+?? ?????? teaser.png # Teaser figure??-������ ? cli-anything-plugin/ # The Claude Code plugin-?? ������ HARNESS.md # Methodology SOP (source of truth)-?? ������ README.md # Plugin documentation-?? ������ QUICKSTART.md # 5-minute getting started-?? ������ PUBLISHING.md # Distribution guide-?? ������ repl_skin.py # Unified REPL interface-?? ������ commands/ # Plugin command definitions-?? ?? ������ cli-anything.md # Main build command-?? ?? ������ refine.md # Expand existing harness coverage-?? ?? ������ test.md # Test runner-?? ?? ������ validate.md # Standards validation-?? ������ scripts/-?? ������ setup-cli-anything.sh # Setup script+?????? ? cli-anything-plugin/ # The Claude Code plugin+?? ?????? HARNESS.md # Methodology SOP (source of truth)+?? ?????? README.md # Plugin documentation+?? ?????? QUICKSTART.md # 5-minute getting started+?? ?????? PUBLISHING.md # Distribution guide+?? ?????? repl_skin.py # Unified REPL interface+?? ?????? commands/ # Plugin command definitions+?? ?? ?????? cli-anything.md # Main build command+?? ?? ?????? refine.md # Expand existing harness coverage+?? ?? ?????? test.md # Test runner+?? ?? ?????? validate.md # Standards validation+?? ?????? scripts/+?? ?????? setup-cli-anything.sh # Setup script??-������ ??? codex-skill/ # Codex skill entry point-������ ? gimp/agent-harness/ # GIMP CLI (107 tests)-������ ??? blender/agent-harness/ # Blender CLI (208 tests)-������ ?? inkscape/agent-harness/ # Inkscape CLI (202 tests)-������ ? audacity/agent-harness/ # Audacity CLI (161 tests)-������ ? browser/agent-harness/ # Browser CLI (DOMShell MCP, new)-������ ? libreoffice/agent-harness/ # LibreOffice CLI (158 tests)-������ ? mailchimp/agent-harness/ # Mailchimp Marketing API CLI (303 commands, 36 unit tests)-������ ? zotero/agent-harness/ # Zotero CLI (new, write import support)-������ ? joplin/agent-harness/ # Joplin CLI (118 tests, new)-������ ? calibre/agent-harness/ # Calibre CLI (58 tests: 38 unit + 20 E2E)-������ ? mubu/agent-harness/ # Mubu CLI (96 tests)-������ ? obs-studio/agent-harness/ # OBS Studio CLI (153 tests)-������ ? nslogger/agent-harness/ # NSLogger CLI (139 tests)-������ ??? kdenlive/agent-harness/ # Kdenlive CLI (155 tests)-������ ? shotcut/agent-harness/ # Shotcut CLI (154 tests)-������ ? zoom/agent-harness/ # Zoom CLI (22 tests)-������ ? musescore/agent-harness/ # MuseScore CLI (56 tests)-������ ? drawio/agent-harness/ # Draw.io CLI (138 tests)-������ ?? eth2-quickstart/agent-harness/ # ETH2 QuickStart CLI (18 unit, 3 e2e skipped)-������ ??? mermaid/agent-harness/ # Mermaid Live Editor CLI (10 tests)-������ ?? anygen/agent-harness/ # AnyGen CLI (50 tests)-������ ??? comfyui/agent-harness/ # ComfyUI CLI (70 tests)-������ ??? notebooklm/agent-harness/ # NotebookLM CLI (experimental, 21 tests)-������ ? dify-workflow/agent-harness/ # Dify Workflow CLI wrapper (11 tests)-������ ??? adguardhome/agent-harness/ # AdGuard Home CLI (36 tests)-������ ??? ollama/agent-harness/ # Ollama CLI (98 tests)-������ ? godot/agent-harness/ # Godot Engine CLI (24 tests)-������ ? sbox/agent-harness/ # s&box CLI (244 tests: 157 unit + 17 orchestrator + 50 e2e + 20 exit-code)-������ ? sketch/agent-harness/ # Sketch CLI (19 tests, Node.js)-������ ? renderdoc/agent-harness/ # RenderDoc CLI (59 tests)-������ ? nsight-graphics/agent-harness/ # Nsight Graphics CLI (51 tests)-������ ? lldb/agent-harness/ # LLDB CLI (27 tests)-������ ? unrealinsights/agent-harness/ # Unreal Insights CLI (50 tests)-������ ? videocaptioner/agent-harness/ # VideoCaptioner CLI (26 tests)-������ ? openscreen/agent-harness/ # Openscreen CLI ?? screen recording editor (101 tests)-������ ?? cloudcompare/agent-harness/ # CloudCompare CLI (88 tests)-������ ? exa/agent-harness/ # Exa CLI (40 tests)-������ ?? cloudanalyzer/agent-harness/ # CloudAnalyzer CLI (14 tests)-������ ? 3MF/agent-harness/ # 3MF Mesh Editor CLI (50+ tests)+?????? ??? codex-skill/ # Codex skill entry point+?????? ? gimp/agent-harness/ # GIMP CLI (107 tests)+?????? ??? blender/agent-harness/ # Blender CLI (208 tests)+?????? ?? inkscape/agent-harness/ # Inkscape CLI (202 tests)+?????? ? audacity/agent-harness/ # Audacity CLI (161 tests)+?????? ? browser/agent-harness/ # Browser CLI (DOMShell MCP, new)+?????? ? libreoffice/agent-harness/ # LibreOffice CLI (158 tests)+?????? ? mailchimp/agent-harness/ # Mailchimp Marketing API CLI (303 commands, 36 unit tests)+?????? ? zotero/agent-harness/ # Zotero CLI (new, write import support)+?????? ? joplin/agent-harness/ # Joplin CLI (118 tests, new)+?????? ? calibre/agent-harness/ # Calibre CLI (58 tests: 38 unit + 20 E2E)+?????? ? mubu/agent-harness/ # Mubu CLI (96 tests)+?????? ? obs-studio/agent-harness/ # OBS Studio CLI (153 tests)+?????? ? nslogger/agent-harness/ # NSLogger CLI (139 tests)+?????? ??? kdenlive/agent-harness/ # Kdenlive CLI (155 tests)+?????? ? shotcut/agent-harness/ # Shotcut CLI (154 tests)+?????? ? zoom/agent-harness/ # Zoom CLI (22 tests)+?????? ? musescore/agent-harness/ # MuseScore CLI (56 tests)+?????? ? drawio/agent-harness/ # Draw.io CLI (138 tests)+?????? ?? eth2-quickstart/agent-harness/ # ETH2 QuickStart CLI (18 unit, 3 e2e skipped)+?????? ??? mermaid/agent-harness/ # Mermaid Live Editor CLI (10 tests)+?????? ?? anygen/agent-harness/ # AnyGen CLI (50 tests)+?????? ??? comfyui/agent-harness/ # ComfyUI CLI (70 tests)+?????? ??? notebooklm/agent-harness/ # NotebookLM CLI (experimental, 21 tests)+?????? ? dify-workflow/agent-harness/ # Dify Workflow CLI wrapper (11 tests)+?????? ??? adguardhome/agent-harness/ # AdGuard Home CLI (36 tests)+?????? ??? ollama/agent-harness/ # Ollama CLI (98 tests)+?????? ? godot/agent-harness/ # Godot Engine CLI (24 tests)+?????? ? sbox/agent-harness/ # s&box CLI (244 tests: 157 unit + 17 orchestrator + 50 e2e + 20 exit-code)+?????? ? sketch/agent-harness/ # Sketch CLI (19 tests, Node.js)+?????? ? renderdoc/agent-harness/ # RenderDoc CLI (59 tests)+?????? ? nsight-graphics/agent-harness/ # Nsight Graphics CLI (51 tests)+?????? ? lldb/agent-harness/ # LLDB CLI (27 tests)+?????? ? unrealinsights/agent-harness/ # Unreal Insights CLI (50 tests)+?????? ? videocaptioner/agent-harness/ # VideoCaptioner CLI (26 tests)+?????? ? openscreen/agent-harness/ # Openscreen CLI ?? screen recording editor (101 tests)+?????? ?? cloudcompare/agent-harness/ # CloudCompare CLI (88 tests)+?????? ? exa/agent-harness/ # Exa CLI (40 tests)+?????? ?? cloudanalyzer/agent-harness/ # CloudAnalyzer CLI (14 tests)+?????? ? 3MF/agent-harness/ # 3MF Mesh Editor CLI (50+ tests)```Each `agent-harness/` contains an installable Python package under `cli_anything.<software>/` with Click CLI, core modules, utils (including `repl_skin.py` and backend wrapper), and comprehensive tests.@@ -1305,7 +1305,7 @@ $ cli-anything-libreoffice --project report.json writer add-heading -t "Q1 Repor?? Added heading: "Q1 Report"$ cli-anything-libreoffice --project report.json writer add-table --rows 4 --cols 3-?? Added 4��3 table+?? Added 4??3 table# Export to real PDF via LibreOffice headless$ cli-anything-libreoffice --project report.json export render output.pdf -p pdf --overwrite@@ -1326,10 +1326,10 @@ $ cli-anything-libreoffice --json document info --project report.json```$ cli-anything-blender-�X�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�[+?X?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?[?? cli-anything-blender v1.0.0 ???? Blender CLI for AI Agents ??-�^�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�T�a+?^?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?T?ablender> scene new --name ProductShot?? Created scene: ProductShot@@ -1338,7 +1338,7 @@ blender[ProductShot]> object add-mesh --type cube --location 0 0 1?? Added mesh: Cube at (0, 0, 1)blender[ProductShot]*> render execute --output render.png --engine CYCLES-?? Rendered: render.png (1920��1080, 2.3 MB) via blender --background+?? Rendered: render.png (1920??1080, 2.3 MB) via blender --backgroundblender[ProductShot]> exitGoodbye! ?@@ -1361,7 +1361,7 @@ The playbook distills key insights from successfully building all 18 diverse, pr| **Use the real software** | The CLI MUST call the actual application for rendering. No Pillow replacements for GIMP, no custom renderers for Blender. Generate valid project files ?? invoke the real backend. || **The Rendering Gap** | GUI apps apply effects at render time. If your CLI manipulates project files but uses a naive export tool, effects get silently dropped. Solution: native renderer ?? filter translation ?? render script. || **Filter Translation** | When mapping effects between formats (MLT ?? ffmpeg), watch for duplicate filter merging, interleaved stream ordering, parameter space differences, and unmappable effects. |-| **Timecode Precision** | Non-integer frame rates (29.97fps) cause cumulative rounding. Use `round()` not `int()`, integer arithmetic for display, and ��1 frame tolerance in tests. |+| **Timecode Precision** | Non-integer frame rates (29.97fps) cause cumulative rounding. Use `round()` not `int()`, integer arithmetic for display, and ??1 frame tolerance in tests. || **Output Verification** | Never trust that export worked because it exited 0. Verify: magic bytes, ZIP/OOXML structure, pixel analysis, audio RMS levels, duration checks. |> See the full methodology: [`cli-anything-plugin/HARNESS.md`](cli-anything-plugin/HARNESS.md)diff --git a/README_CN.md b/README_CN.mdindex 3b8cb8cac..908694243 100644--- a/README_CN.md+++ b/README_CN.md@@ -685,9 +685,9 @@ nsight-graphics 51 passed ??? (46 unit/CLI + 5 local e2e)unrealinsights 50 passed ??? (49 unit + 1 e2e, 9 backend-gated e2e skipped)sketch 19 passed ??? (19 jest, Node.js)3mf 50 passed ??? (50 unit)-joplin 123 passed ??? (96 unit + 27 e2e, 1 skipped on Windows)+joplin 131 passed ??? (104 unit + 27 e2e, 1 skipped on Windows)??????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????-TOTAL 1,947 passed ??? 100% pass rate+TOTAL 1,955 passed ??? 100% pass rate```---@@ -870,7 +870,7 @@ HARNESS.md ????????????????????? CLI ???????????????????? Agent ????????????????| **?????????????** | CLI ???????????????????????????????????? Pillow ???? GIMP???????????????????????? Blender???????????????????????????????? ??? ???????????????? || **???????** | GUI ????????????????????????????????????????? CLI ???????????????????????????????????????????????????????????????????????????????? ??? ??????? ??? ????????????? || **???????** | ????????????????????????????? MLT ??? ffmpeg????????????????????????????????????????????????????????????????????????????? |-| **?????????** | ???????????????? 29.97fps???????????????????????? `round()` ????? `int()`???????????????????????????????? �1 ?????? |+| **?????????** | ???????????????? 29.97fps???????????????????????? `round()` ????? `int()`???????????????????????????????? ?1 ?????? || **????????** | ????????????????????? 0 ???????????????????????????????????ZIP/OOXML ?????????????????????????? RMS ????????????????????? |> ??????????????[`cli-anything-plugin/HARNESS.md`](cli-anything-plugin/HARNESS.md)diff --git a/joplin/agent-harness/JOPLIN.md b/joplin/agent-harness/JOPLIN.mdindex 5b77decd8..bb90d1d20 100644--- a/joplin/agent-harness/JOPLIN.md+++ b/joplin/agent-harness/JOPLIN.md@@ -125,8 +125,8 @@ For real backend runs, ensure `joplin` is installed and available in `PATH`.Current validation baseline (Windows + Joplin CLI 3.6.2):-- `python -m pytest -q cli_anything/joplin/tests/test_core.py` ? `96 passed`-- `python -m pytest -q cli_anything/joplin/tests` ? `123 passed, 1 skipped`+- `python -m pytest -q cli_anything/joplin/tests/test_core.py` -> `104 passed`+- `python -m pytest -q cli_anything/joplin/tests` -> `131 passed, 1 skipped`## Development notes@@ -162,3 +162,11 @@ Current validation baseline (Windows + Joplin CLI 3.6.2):a clear `RuntimeError` rather than letting a "permanent" delete fallthrough to a soft trash move. The flag is forwarded as the long-form`--permanent` (and `--force` for force), never the short `-p` / `-f`.+- `server start --exit-early` / `--quiet` and `e2ee decrypt --force` are+ gated by the same `joplin help <command>` probe (see+ `_cli_supports_flag` in `core/backend.py`). They are real options of+ Joplin 3.x, but the same "silently ignored unknown option" behaviour+ means dropping them on older builds would either hang the harness on+ the server foreground loop or deadlock e2ee on an interactive+ master-password prompt. The probe raises a clear, actionable error in+ those cases.diff --git a/joplin/agent-harness/README.md b/joplin/agent-harness/README.mdindex e72b021f2..266c207b7 100644--- a/joplin/agent-harness/README.md+++ b/joplin/agent-harness/README.md@@ -65,8 +65,8 @@ cli-anything-joplin --dry-run --project ./demo.joplin-harness.json todos createCurrent validation baseline (Windows + Joplin CLI 3.6.2):-- `python -m pytest -q cli_anything/joplin/tests/test_core.py` ? `96 passed`-- `python -m pytest -q cli_anything/joplin/tests` ? `123 passed, 1 skipped`+- `python -m pytest -q cli_anything/joplin/tests/test_core.py` -> `104 passed`+- `python -m pytest -q cli_anything/joplin/tests` -> `131 passed, 1 skipped`See `cli_anything/joplin/tests/TEST.md` for the full plan (91 unit + 27 e2e,2 skipped on Windows) and `cli_anything/joplin/WORKFLOWS.md` for the verifieddiff --git a/joplin/agent-harness/cli_anything/joplin/README.md b/joplin/agent-harness/cli_anything/joplin/README.mdindex 8e107d18b..786756a95 100644--- a/joplin/agent-harness/cli_anything/joplin/README.md+++ b/joplin/agent-harness/cli_anything/joplin/README.md@@ -121,8 +121,8 @@ CLI_ANYTHING_FORCE_INSTALLED=1 python -m pytest -v -s cli_anything/joplin/tests/Current validation baseline (Windows + Joplin CLI 3.6.2):-- `python -m pytest -q cli_anything/joplin/tests/test_core.py` ? `96 passed`-- `python -m pytest -q cli_anything/joplin/tests` ? `123 passed, 1 skipped`+- `python -m pytest -q cli_anything/joplin/tests/test_core.py` -> `104 passed`+- `python -m pytest -q cli_anything/joplin/tests` -> `131 passed, 1 skipped`See `cli_anything/joplin/tests/TEST.md` for the full test plan and`cli_anything/joplin/WORKFLOWS.md` for the verified workflow inventory.diff --git a/joplin/agent-harness/cli_anything/joplin/WORKFLOWS.md b/joplin/agent-harness/cli_anything/joplin/WORKFLOWS.mdindex 990c3a46f..1a3ff263b 100644--- a/joplin/agent-harness/cli_anything/joplin/WORKFLOWS.md+++ b/joplin/agent-harness/cli_anything/joplin/WORKFLOWS.md@@ -131,3 +131,13 @@ tag.add, tag.remove, attach.add, interop.export, note.remove, notebook.remove`--force`); the short `-p` is intentionally avoided since Joplin uses`-p` for `--parent` in `mkbook` and `--permanent` only became availablein 3.x.+- `server start --exit-early` / `--quiet` and `e2ee decrypt --force` are+ also probe-gated through the shared `_cli_supports_flag` helper in+ `core/backend.py`. They are documented options of Joplin 3.x+ (`command-server.js`, `command-e2ee.js`), but because Joplin would+ silently ignore them on older builds the harness refuses to send them+ in that case. Without `--exit-early` the harness subprocess would block+ forever waiting for the foreground server; without `--force`, e2ee+ decrypt would deadlock on an interactive master-password prompt. The+ probe is cached per `(binary, command, flag)` so workflows that issue+ many starts pay one help call per flag.diff --git a/joplin/agent-harness/cli_anything/joplin/core/backend.py b/joplin/agent-harness/cli_anything/joplin/core/backend.pyindex 10df3fdf8..c921b5f6f 100644--- a/joplin/agent-harness/cli_anything/joplin/core/backend.py+++ b/joplin/agent-harness/cli_anything/joplin/core/backend.py@@ -6,6 +6,35 @@ from pathlib import Pathfrom cli_anything.joplin.utils.joplin_backend import BackendConfig, find_joplin, run_joplin_command, run_joplin_json+# Cache `joplin help <command>` flag-support lookups per (binary, command, flag).+# Joplin's CLI silently ignores unknown options instead of erroring, so we must+# probe `help` before sending optional flags whose support varies by version+# (`server start --exit-early/--quiet`, `e2ee decrypt --force`). Without this,+# an older Joplin would no-op the request while still reporting success.+_FLAG_SUPPORT_CACHE: dict[str, bool] = {}+++def _cli_supports_flag(config: BackendConfig, command_name: str, flag: str) -> bool:+ """Return True iff `joplin help <command_name>` advertises ``flag``.++ Probes are cached per (binary, command, flag) so a workflow that issues+ many e.g. permanent deletes only spawns one help subprocess. Any failure+ of the probe itself (network, missing binary, ...) is treated as "flag+ not supported" so callers raise a clear error instead of silently+ sending an unknown option.+ """+ key = f"{config.binary or 'joplin'}:{command_name}:{flag}"+ if key in _FLAG_SUPPORT_CACHE:+ return _FLAG_SUPPORT_CACHE[key]+ try:+ result = run_joplin_command(["help", command_name], config, timeout=30)+ supported = flag in (result.get("stdout") or "")+ except Exception:+ supported = False+ _FLAG_SUPPORT_CACHE[key] = supported+ return supported++def _npm_global_root() -> Path | None:"""Best-effort lookup of npm's global ``node_modules`` directory.@@ -150,10 +179,33 @@ def server_status(config: BackendConfig) -> dict:def server_start(config: BackendConfig, exit_early: bool = True, quiet: bool = False) -> dict:+ """Start Joplin's API server.++ ``--exit-early`` and ``--quiet`` are both documented options of+ ``joplin server`` (see ``command-server.js`` in Joplin 3.x), but Joplin+ silently ignores unknown options on older builds. Because the default+ workflow relies on ``--exit-early`` to return promptly, we probe+ ``joplin help server`` first and refuse with a clear error rather than+ block forever on a build that omits the flag.+ """args = ["server", "start"]if exit_early:+ if not _cli_supports_flag(config, "server", "--exit-early"):+ raise RuntimeError(+ "Joplin CLI `server start` does not advertise `--exit-early` "+ "(documented since Joplin 3.x). Refusing to send the flag "+ "because Joplin would silently ignore it and the harness "+ "would then block forever waiting for the server process to "+ "exit. Upgrade Joplin, or call `server_start(exit_early=False)` "+ "to run in foreground (`--wait`) mode."+ )args.append("--exit-early")if quiet:+ if not _cli_supports_flag(config, "server", "--quiet"):+ raise RuntimeError(+ "Joplin CLI `server start` does not advertise `--quiet` on "+ "this build. Omit `quiet=True` or upgrade Joplin."+ )args.append("--quiet")# When exit_early is True the CLI returns as soon as the server is up# (~5 s), so a 300 s safety cap is reasonable. When exit_early is False@@ -185,12 +237,30 @@ def e2ee_decrypt(retry_failed_items: bool = False,force: bool = False,) -> dict:+ """Decrypt E2EE-encrypted items / a string.++ ``--force`` ("do not ask for input on failure") is a documented option of+ ``joplin e2ee`` (see ``command-e2ee.js`` -- it's also referenced via+ ``args.options.force`` inside the action). It is essential for the+ non-interactive workflow, since without it Joplin prompts on the TTY for+ a master password and the harness subprocess would hang. As with+ ``server start``, we probe ``joplin help e2ee`` to make sure the+ installed build advertises the flag, since unknown options are silently+ ignored by Joplin.+ """args = ["e2ee", "decrypt"]if encrypted_text:args.append(encrypted_text)if retry_failed_items:args.append("--retry-failed-items")if force:+ if not _cli_supports_flag(config, "e2ee", "--force"):+ raise RuntimeError(+ "Joplin CLI `e2ee decrypt` does not advertise `--force` on "+ "this build. Refusing to send the flag because Joplin would "+ "silently ignore it and could then block on an interactive "+ "master-password prompt. Omit `force=True` or upgrade Joplin."+ )args.append("--force")return run_joplin_command(args, config, timeout=600)diff --git a/joplin/agent-harness/cli_anything/joplin/core/session.py b/joplin/agent-harness/cli_anything/joplin/core/session.pyindex 0d6ce9044..9e3bed7f2 100644--- a/joplin/agent-harness/cli_anything/joplin/core/session.py+++ b/joplin/agent-harness/cli_anything/joplin/core/session.py@@ -1,13 +1,70 @@from __future__ import annotations+import contextlibimport copyimport jsonimport os+import sys+import timefrom dataclasses import dataclass, fieldfrom typing import Optionalfrom cli_anything.joplin.core import project as project_mod+# ---------------------------------------------------------------------------+# Cross-platform exclusive file locking+# ---------------------------------------------------------------------------+# We want *real* mutual exclusion, not just a token file presence check.+# On POSIX we use fcntl.flock(LOCK_EX); on Windows msvcrt.locking.+# Both block until the lock is free, giving us a simple, reliable protocol:+# 1. open/create the .lock file+# 2. acquire an exclusive lock (blocks if another process holds it)+# 3. write data atomically via tmp → os.replace+# 4. release the lock++if sys.platform == "win32":+ import msvcrt as _msvcrt++ @contextlib.contextmanager+ def _exclusive_lock(fd: int):+ """Acquire an exclusive lock on the open file descriptor *fd*."""+ # msvcrt.locking works on byte ranges; we lock the first byte.+ # Retry loop: locking raises OSError(EDEADLK) if the lock is busy+ # (unlike fcntl which blocks). We do an exponential-back-off retry+ # so that concurrent agents don't race on the first try.+ delay = 0.05+ while True:+ try:+ _msvcrt.locking(fd, _msvcrt.LK_NBLCK, 1)+ break+ except OSError:+ if delay > 10:+ raise RuntimeError(+ "Could not acquire project lock after retries (Windows)"+ )+ time.sleep(delay)+ delay = min(delay * 2, 2.0)+ try:+ yield+ finally:+ try:+ os.lseek(fd, 0, os.SEEK_SET)+ _msvcrt.locking(fd, _msvcrt.LK_UNLCK, 1)+ except OSError:+ pass # best-effort unlock; fd will be closed immediately after++else:+ import fcntl as _fcntl++ @contextlib.contextmanager+ def _exclusive_lock(fd: int):+ """Acquire an exclusive lock on the open file descriptor *fd*."""+ _fcntl.flock(fd, _fcntl.LOCK_EX) # blocks until free+ try:+ yield+ finally:+ _fcntl.flock(fd, _fcntl.LOCK_UN)+@dataclassclass Session:@@ -87,12 +144,19 @@ class Session:os.makedirs(parent, exist_ok=True)lock_path = f"{path}.lock"+ # O_CREAT | O_RDWR: create the lock file if absent; never truncate it+ # so an existing holder's lock byte is not disturbed.lock_fd = os.open(lock_path, os.O_CREAT | os.O_RDWR)try:- tmp = f"{path}.tmp"- with open(tmp, "w", encoding="utf-8") as f:- json.dump(data, f, indent=2, ensure_ascii=False)- os.replace(tmp, path)+ # Acquire a real cross-process exclusive lock before writing.+ # _exclusive_lock blocks (POSIX) or retries with back-off (Windows)+ # until no other process holds the lock. This prevents two+ # concurrent agent workers from racing on the shared .tmp file.+ with _exclusive_lock(lock_fd):+ tmp = f"{path}.tmp"+ with open(tmp, "w", encoding="utf-8") as f:+ json.dump(data, f, indent=2, ensure_ascii=False)+ os.replace(tmp, path)finally:os.close(lock_fd)diff --git a/joplin/agent-harness/cli_anything/joplin/skills/SKILL.md b/joplin/agent-harness/cli_anything/joplin/skills/SKILL.mdindex 635a6abfd..36572995c 100644--- a/joplin/agent-harness/cli_anything/joplin/skills/SKILL.md+++ b/joplin/agent-harness/cli_anything/joplin/skills/SKILL.md@@ -106,5 +106,5 @@ CLI_ANYTHING_FORCE_INSTALLED=1 python -m pytest -v -s cli_anything/joplin/tests/Current validation baseline (Windows + Joplin CLI 3.6.2):-- `python -m pytest -q cli_anything/joplin/tests/test_core.py` ? `96 passed`-- `python -m pytest -q cli_anything/joplin/tests` ? `123 passed, 1 skipped`+- `python -m pytest -q cli_anything/joplin/tests/test_core.py` -> `104 passed`+- `python -m pytest -q cli_anything/joplin/tests` -> `131 passed, 1 skipped`diff --git a/joplin/agent-harness/cli_anything/joplin/tests/TEST.md b/joplin/agent-harness/cli_anything/joplin/tests/TEST.mdindex 1414267c9..1d23e75e7 100644--- a/joplin/agent-harness/cli_anything/joplin/tests/TEST.md+++ b/joplin/agent-harness/cli_anything/joplin/tests/TEST.md@@ -8,7 +8,7 @@ The suite has two files:Real-backend classes are skipped automatically when `joplin` is not on `PATH`.-## test_core.py (96 tests)+## test_core.py (104 tests)Pure Python tests covering the harness surface. Safe to run anywhere withouta Joplin backend.@@ -20,6 +20,12 @@ Coverage areas:redo cleared on new snapshot, save/save-without-path, `mark_dirty`- Session save regression: nested project path auto-creates missing parentdirectories before lock/write+- Session file locking: `_locked_save_json` acquires a real cross-process+ exclusive lock (`fcntl.flock` on POSIX, `msvcrt.locking` with back-off+ on Windows) so concurrent agent workers cannot race on the shared `.tmp`+ file. Tests verify: lock is acquired and released on a single save (so+ a subsequent save can proceed), and four concurrent threads writing to+ the same file all complete successfully with the file remaining valid JSON- Backend runner: `find_joplin`, profile/no-profile invocation, error path,benign Node warning handling (scrubbed copy used only for the non-zero exitdecision; returned `stdout`/`stderr` stay verbatim), mixed warning+real-error@@ -51,6 +57,19 @@ Coverage areas:no probe when `permanent=False`, clear RuntimeError on unsupported CLI,cached probe (one help call across N permanent deletes), and thenotebooks variant of the same guard+- `server start --exit-early/--quiet` guard and `e2ee decrypt --force`+ guard: same defensive pattern via a generalised+ `_cli_supports_flag(config, command, flag)` helper with a+ per-(binary, command, flag) cache. `server start(exit_early=True)`+ refuses with an actionable error suggesting `exit_early=False`+ (`--wait` mode) on builds that omit `--exit-early`, because Joplin+ would otherwise silently ignore the flag and the harness subprocess+ would block forever. `e2ee decrypt(force=True)` refuses on builds+ without `--force` to avoid deadlocking on an interactive master-+ password prompt. Tests cover: long-form forwarded when supported,+ no probe when the flag was not requested, refusal on unsupported+ builds (server / quiet / e2ee), and that the probe is cached so N+ starts only emit help once per distinct flag- JSON envelope shape (success + error)- JSON contract per command group: notebooks, notes, todos, tags, search,sync, interop, config, session, attach, status, backend, server, e2ee@@ -182,3 +201,10 @@ CLI_ANYTHING_FORCE_INSTALLED=1 python -m pytest -v -s cli_anything/joplin/tests/the flag (Joplin terminal CLI >= 3.0). On older Joplin builds the harnessraises `RuntimeError` rather than silently letting the delete go to thetrash. Omit `--permanent` to use a soft delete on any version.+- `server start --exit-early`, `server start --quiet`, and `e2ee decrypt+ --force` are also gated through a `joplin help <command>` probe. They+ are real options of Joplin terminal CLI 3.x (see `command-server.js` and+ `command-e2ee.js`), but Joplin silently ignores unknown options, so the+ harness refuses to send them on older builds and surfaces a clear error+ instead of either blocking forever (server) or hanging on an interactive+ master-password prompt (e2ee).diff --git a/joplin/agent-harness/cli_anything/joplin/tests/test_core.py b/joplin/agent-harness/cli_anything/joplin/tests/test_core.pyindex 06fd5e3b9..088a1273a 100644--- a/joplin/agent-harness/cli_anything/joplin/tests/test_core.py+++ b/joplin/agent-harness/cli_anything/joplin/tests/test_core.py@@ -193,6 +193,67 @@ def test_session_save_creates_missing_parent_directories(tmp_path):assert nested.parent.is_dir()+def test_session_save_real_lock_held_then_released(tmp_path):+ """The exclusive lock must be acquired and released correctly for a+ normal single-process save, so that a subsequent save on the same path+ can acquire it again without blocking."""+ project_path = tmp_path / "project.json"+ sess = Session()+ sess.set_project(project_mod.create_project(name="lock-test"), str(project_path))+ sess.save_session()++ # A second save on the same path must succeed (lock was released by the+ # first save). If _locked_save_json fails to release, this deadlocks or+ # raises, failing the test.+ sess.snapshot("change")+ sess.save_session()+ assert project_path.exists()+++def test_session_save_lock_prevents_tmp_collision(tmp_path):+ """Two threads calling _locked_save_json on the same path concurrently+ must each write their own data atomically -- neither write should be lost+ and the file must remain valid JSON after both finish."""+ import threading++ project_path = tmp_path / "shared.json"++ # Pre-create the file so both threads are working on an existing path.+ sess0 = Session()+ sess0.set_project(project_mod.create_project(name="init"), str(project_path))+ sess0.save_session()++ errors: list[Exception] = []+ results: list[str] = []++ def writer(name: str) -> None:+ try:+ sess = Session()+ proj = project_mod.create_project(name=name)+ sess.set_project(proj, str(project_path))+ # Each writer saves from a snapshot so _modified is True.+ sess.snapshot(f"writer {name}")+ sess.save_session()+ results.append(name)+ except Exception as exc:+ errors.append(exc)++ threads = [threading.Thread(target=writer, args=(f"writer-{i}",)) for i in range(4)]+ for t in threads:+ t.start()+ for t in threads:+ t.join(timeout=10)++ assert not errors, f"Concurrent saves raised: {errors}"+ assert len(results) == 4, f"Not all writers completed: {results}"++ # The file must still be valid JSON after all concurrent writes.+ with open(project_path, encoding="utf-8") as fh:+ content = json.load(fh)+ assert isinstance(content, dict)+ assert "name" in content++def test_session_set_project_clears_undo_redo():sess = Session()sess.set_project(project_mod.create_project(name="a"))@@ -484,25 +545,31 @@ def test_backend_run_command_timeout(monkeypatch):assert "timed out" in str(excinfo.value)+def _server_help_supporting_all_flags():+ return (+ "server <command>\n"+ " --exit-early Allow the command to exit while the server is still running...\n"+ " --quiet Log less information to the console...\n"+ )++def test_backend_server_start_exit_early_uses_finite_timeout(monkeypatch):"""P2 regression: server_start(exit_early=True) must pass a finite timeout."""captured = {}- class Proc:- returncode = 0- stdout = "Server started"- stderr = ""-- def fake_run(cmd, *a, **k):- captured["timeout"] = k.get("timeout")- return Proc()+ def fake(args, cfg, timeout=120):+ if args[:1] == ["help"]:+ return {"command": args, "returncode": 0, "stdout": _server_help_supporting_all_flags(), "stderr": ""}+ captured["args"] = args+ captured["timeout"] = timeout+ return {"command": args, "returncode": 0, "stdout": "", "stderr": ""}+ backend_core._FLAG_SUPPORT_CACHE.clear()monkeypatch.setattr(backend_core, "find_joplin", lambda _: "joplin")- monkeypatch.setattr(backend_core, "run_joplin_command",- lambda args, cfg, timeout=120: captured.update({"timeout": timeout}) or- {"command": args, "returncode": 0, "stdout": "", "stderr": ""})+ monkeypatch.setattr(backend_core, "run_joplin_command", fake)cfg = joplin_backend.BackendConfig()backend_core.server_start(cfg, exit_early=True)+ assert captured["args"] == ["server", "start", "--exit-early"]assert captured["timeout"] is not Noneassert captured["timeout"] > 0@@ -512,14 +579,145 @@ def test_backend_server_start_no_exit_early_uses_no_timeout(monkeypatch):a long-lived server process is never killed by a hard deadline."""captured = {}- monkeypatch.setattr(backend_core, "run_joplin_command",- lambda args, cfg, timeout=120: captured.update({"timeout": timeout}) or- {"command": args, "returncode": 0, "stdout": "", "stderr": ""})+ def fake(args, cfg, timeout=120):+ # exit_early=False must NOT probe (no flag to gate)+ if args[:1] == ["help"]:+ captured.setdefault("help_called", True)+ captured["args"] = args+ captured["timeout"] = timeout+ return {"command": args, "returncode": 0, "stdout": "", "stderr": ""}++ backend_core._FLAG_SUPPORT_CACHE.clear()+ monkeypatch.setattr(backend_core, "run_joplin_command", fake)cfg = joplin_backend.BackendConfig()backend_core.server_start(cfg, exit_early=False)+ assert captured["args"] == ["server", "start"]assert captured["timeout"] is None, (f"Expected timeout=None for --wait mode, got {captured['timeout']}")+ assert "help_called" not in captured, "Should not probe help when no flag is needed"+++def test_backend_server_start_refuses_when_exit_early_unsupported(monkeypatch):+ """Regression: on older Joplin builds that don't advertise --exit-early,+ refuse rather than silently send a flag Joplin would ignore (which would+ leave the harness blocked forever waiting for the foreground server)."""+ sent = []++ def fake(args, cfg, timeout=120):+ if args[:1] == ["help"]:+ # Old Joplin: usage only, no flags listed.+ return {"command": args, "returncode": 0, "stdout": "server <command>\n", "stderr": ""}+ sent.append(args)+ return {"command": args, "returncode": 0, "stdout": "", "stderr": ""}++ backend_core._FLAG_SUPPORT_CACHE.clear()+ monkeypatch.setattr(backend_core, "run_joplin_command", fake)+ cfg = joplin_backend.BackendConfig()+ with pytest.raises(RuntimeError) as excinfo:+ backend_core.server_start(cfg, exit_early=True)+ assert "--exit-early" in str(excinfo.value)+ assert "exit_early=False" in str(excinfo.value)+ assert sent == [], "Server start command must not be sent when probe fails"+++def test_backend_server_start_refuses_when_quiet_unsupported(monkeypatch):+ """Same defensive check for --quiet."""+ sent = []++ def fake(args, cfg, timeout=120):+ if args[:1] == ["help"]:+ # Build that has --exit-early but not --quiet.+ return {"command": args, "returncode": 0, "stdout": "server\n --exit-early ...\n", "stderr": ""}+ sent.append(args)+ return {"command": args, "returncode": 0, "stdout": "", "stderr": ""}++ backend_core._FLAG_SUPPORT_CACHE.clear()+ monkeypatch.setattr(backend_core, "run_joplin_command", fake)+ cfg = joplin_backend.BackendConfig()+ with pytest.raises(RuntimeError) as excinfo:+ backend_core.server_start(cfg, exit_early=True, quiet=True)+ assert "--quiet" in str(excinfo.value)+ assert sent == []+++def test_backend_server_start_probe_cached_across_calls(monkeypatch):+ """The help probe must be cached per (binary, command, flag) so repeated+ server_start calls don't pay a subprocess cost each time."""+ help_calls = 0+ started = 0++ def fake(args, cfg, timeout=120):+ nonlocal help_calls, started+ if args[:1] == ["help"]:+ help_calls += 1+ return {"command": args, "returncode": 0, "stdout": _server_help_supporting_all_flags(), "stderr": ""}+ started += 1+ return {"command": args, "returncode": 0, "stdout": "", "stderr": ""}++ backend_core._FLAG_SUPPORT_CACHE.clear()+ monkeypatch.setattr(backend_core, "run_joplin_command", fake)+ cfg = joplin_backend.BackendConfig()+ for _ in range(3):+ backend_core.server_start(cfg, exit_early=True, quiet=True)+ # Two distinct flags (--exit-early, --quiet) => one probe each, both cached.+ assert help_calls == 2, f"expected 2 help probes total, got {help_calls}"+ assert started == 3+++def test_backend_e2ee_decrypt_force_supported(monkeypatch):+ """When `joplin help e2ee` advertises -f, --force we send the long form."""+ captured = {}++ def fake(args, cfg, timeout=120):+ if args[:1] == ["help"]:+ return {"command": args, "returncode": 0,+ "stdout": "e2ee\n -f, --force Do not ask for input on failure\n", "stderr": ""}+ captured["args"] = args+ return {"command": args, "returncode": 0, "stdout": "", "stderr": ""}++ backend_core._FLAG_SUPPORT_CACHE.clear()+ monkeypatch.setattr(backend_core, "run_joplin_command", fake)+ cfg = joplin_backend.BackendConfig()+ backend_core.e2ee_decrypt(cfg, force=True)+ assert captured["args"] == ["e2ee", "decrypt", "--force"]+++def test_backend_e2ee_decrypt_force_refuses_when_unsupported(monkeypatch):+ """On builds that don't advertise --force, refuse rather than silently+ let the e2ee subprocess deadlock on an interactive master-password prompt."""+ sent = []++ def fake(args, cfg, timeout=120):+ if args[:1] == ["help"]:+ return {"command": args, "returncode": 0,+ "stdout": "e2ee\n -p, --password ...\n -v, --verbose ...\n", "stderr": ""}+ sent.append(args)+ return {"command": args, "returncode": 0, "stdout": "", "stderr": ""}++ backend_core._FLAG_SUPPORT_CACHE.clear()+ monkeypatch.setattr(backend_core, "run_joplin_command", fake)+ cfg = joplin_backend.BackendConfig()+ with pytest.raises(RuntimeError) as excinfo:+ backend_core.e2ee_decrypt(cfg, force=True)+ assert "--force" in str(excinfo.value)+ assert "interactive" in str(excinfo.value).lower() or "prompt" in str(excinfo.value).lower()+ assert sent == []+++def test_backend_e2ee_decrypt_no_force_skips_probe(monkeypatch):+ """force=False is the default; we must not probe help in the default path."""+ seen = []++ def fake(args, cfg, timeout=120):+ seen.append(args)+ return {"command": args, "returncode": 0, "stdout": "", "stderr": ""}++ backend_core._FLAG_SUPPORT_CACHE.clear()+ monkeypatch.setattr(backend_core, "run_joplin_command", fake)+ cfg = joplin_backend.BackendConfig()+ backend_core.e2ee_decrypt(cfg, encrypted_text="abc", retry_failed_items=True)+ assert seen == [["e2ee", "decrypt", "abc", "--retry-failed-items"]]def test_backend_run_json_parse(monkeypatch):@@ -851,12 +1049,25 @@ def test_tags_tagnotes_uses_tag_list(monkeypatch):def test_sync_import_config_and_backend_args(monkeypatch):+ # Non-help command invocations only; help probes are responded to inline+ # so they don't pollute the parity assertions below.captured = []def fake_command(args, cfg, timeout=120):+ if args[:1] == ["help"]:+ # Respond as if the modern Joplin CLI: advertise every flag we+ # may probe so server_start/e2ee_decrypt don't refuse.+ if args == ["help", "server"]:+ stdout = "server\n --exit-early ...\n --quiet ...\n"+ elif args == ["help", "e2ee"]:+ stdout = "e2ee\n -f, --force ...\n"+ else:+ stdout = ""+ return {"command": args, "returncode": 0, "stdout": stdout, "stderr": ""}captured.append(args)return {"returncode": 0}+ backend_core._FLAG_SUPPORT_CACHE.clear()monkeypatch.setattr(sync_core, "run_joplin_command", fake_command)monkeypatch.setattr(interop_core, "run_joplin_command", fake_command)monkeypatch.setattr(config_core, "run_joplin_command", fake_command)diff --git a/skills/cli-anything-joplin/SKILL.md b/skills/cli-anything-joplin/SKILL.mdindex 616c955db..91d85ba78 100644--- a/skills/cli-anything-joplin/SKILL.md+++ b/skills/cli-anything-joplin/SKILL.md@@ -98,5 +98,5 @@ When `--json` is enabled, commands return:Current validation baseline (Windows + Joplin CLI 3.6.2):-- `python -m pytest -q cli_anything/joplin/tests/test_core.py` ? `96 passed`-- `python -m pytest -q cli_anything/joplin/tests` ? `123 passed, 1 skipped`+- `python -m pytest -q cli_anything/joplin/tests/test_core.py` -> `104 passed`+- `python -m pytest -q cli_anything/joplin/tests` -> `131 passed, 1 skipped`