Skip to content

"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.md
index 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.&nbsp;&nbsp;[**??����??**](README_CN.md) | [**�ձ��Z��??�����**](README_JA.md)
+**One Command Line**: Make any software agent-ready for Pi, OpenClaw, nanobot, Cursor, Claude Code, etc.&nbsp;&nbsp;[**????????**](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?a
blender> 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 --background
blender[ProductShot]> exit
Goodbye! ?
@@ -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.md
index 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.md
index 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 fall
through 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.md
index 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 create
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 plan (91 unit + 27 e2e,
2 skipped on Windows) and `cli_anything/joplin/WORKFLOWS.md` for the verified
diff --git a/joplin/agent-harness/cli_anything/joplin/README.md b/joplin/agent-harness/cli_anything/joplin/README.md
index 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.md
index 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 available
in 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.py
index 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 Path
from 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.py
index 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 contextlib
import copy
import json
import os
+import sys
+import time
from dataclasses import dataclass, field
from typing import Optional
from 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)
+
@dataclass
class 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.md
index 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.md
index 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 without
a 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 parent
directories 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 exit
decision; 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 the
notebooks 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 harness
raises `RuntimeError` rather than silently letting the delete go to the
trash. 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.py
index 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 None
assert 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.md
index 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`