runspool 0.2.0__tar.gz → 0.2.1__tar.gz

runspool-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      # skip-existing below must not hide a forgotten version bump: a release tag
+      # has to match the version being published.
+      - name: Check the tag matches the version
+        if: github.event_name == 'release'
+        run: |
+          version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          test "v$version" = "${{ github.event.release.tag_name }}" || {
+            echo "release tag ${{ github.event.release.tag_name }} != pyproject version v$version"; exit 1; }
+
+      # RunSpool and its official plugin(s). Example plugins are not published.
+      - name: Build distributions
+        run: |
+          uv build --package runspool -o dist
+          uv build --package runspool-wechat -o dist
+
+      # A release may bump only some packages: versions already on PyPI are skipped.
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

{runspool-0.2.0 → runspool-0.2.1}/CHANGELOG.md

@@ -6,6 +6,22 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-10-04
+
+### Added
+- **`daemon/tick` event**: the daemon emits it after every scheduling round with a
+  `DaemonTick` (`round`, `now`), so plugins can do periodic maintenance (sweep a
+  cache, rotate files) without a process of their own. A listener that raises is
+  logged and skipped; scheduling carries on.
+- **`default_workflow` setting**: the workflow `runspool add` uses without
+  `--workflow` (still `local_file` when unset). `runspool doctor` reports a
+  default that no workflow defines.
+
+### Fixed
+- `runspool.__version__` said 0.1.0; it now reads the installed version.
+- `runspool add` with an unknown workflow printed the error prefix twice
+  (`undefined workflow: undefined workflow: 'x'`).
+
 ## [0.2.0] - 2026-10-04
 
 RunSpool is now built from plugins on a small kernel. Everything the engine does —
@@ -151,6 +167,7 @@ Initial release.
 - Documentation (`docs/`), English + Simplified Chinese READMEs, and CI running
   ruff, pytest (Python 3.11/3.12/3.13), and an example smoke test.
 
-[Unreleased]: https://github.com/ethan-sun-dev/runspool/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/ethan-sun-dev/runspool/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/ethan-sun-dev/runspool/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/ethan-sun-dev/runspool/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/ethan-sun-dev/runspool/releases/tag/v0.1.0

{runspool-0.2.0 → runspool-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: runspool
-Version: 0.2.0
+Version: 0.2.1
 Summary: A local-first CLI workflow engine for reliable personal automation.
 Project-URL: Homepage, https://github.com/ethan-sun-dev/runspool
 Project-URL: Repository, https://github.com/ethan-sun-dev/runspool

{runspool-0.2.0 → runspool-0.2.1}/RELEASING.md

@@ -6,7 +6,11 @@ Example plugins (`plugins/runspool-example-*`) are not published.
 ## 1. Prepare
 
 - Set the version in `pyproject.toml` (RunSpool) and in each published plugin's
-  `pyproject.toml` (`plugins/runspool-wechat`). Plugins declare the RunSpool range
+  `pyproject.toml` (`plugins/runspool-wechat`). A plugin with no changes may keep its
+  version: the publish workflow skips files already on PyPI. That also means a
+  plugin changed *without* a version bump is silently not published: check
+  `git diff vPREVIOUS -- plugins/<name>` before keeping a version. The workflow
+  does fail when the release tag does not match RunSpool's own version. Plugins declare the RunSpool range
   they support, e.g. `runspool>=0.2,<0.3`; RunSpool refuses to load a plugin outside
   its range (a profile can exempt an exact version with `allow`).
 - Move the `[Unreleased]` notes in `CHANGELOG.md` under the new version and date,

{runspool-0.2.0 → runspool-0.2.1}/docs/cli.md

@@ -46,7 +46,8 @@ runspool add ./chapter-2 --parent 1 --workflow translate
 
 - `<input>` — the task input (e.g. a file or directory path). An input that
   names an existing file or directory is stored as an absolute path.
-- `-w/--workflow NAME` — workflow to use (default `local_file`).
+- `-w/--workflow NAME` — workflow to use (default: the profile's `default_workflow`,
+  else `local_file`).
 - `--name NAME` — human-readable label (defaults to a value derived by the first
   step, e.g. the file stem).
 - `--meta KEY=VALUE` — task metadata, repeatable. Values are strings; steps read

{runspool-0.2.0 → runspool-0.2.1}/docs/plugins.md

@@ -266,6 +266,7 @@ The events RunSpool itself dispatches:
 | --- | --- | --- |
 | `step/pre-execute` | waterfall | `(request, next)`: decides whether a claimed step may run |
 | `approval/request` | emit | `(task)`: a task has started waiting for approval |
+| `daemon/tick` | emit | `(tick)`: the daemon finished a scheduling round (`DaemonTick`: `round`, `now`) |
 | `internal/status` | emit | `(fiber)`: a plugin's lifecycle state changed (kernel internal) |
 
 `step/pre-execute` and `approval/request` are dispatched on the worker thread
@@ -336,6 +337,30 @@ notification plugin listens to it:
 ctx.on("approval/request", lambda task: notify_owner(f"task {task['id']} awaits approval"))
 ```
 
+### `daemon/tick`
+
+The resident daemon emits it once per round, after scheduling, with a
+`runspool.daemon.DaemonTick` (`round`: 1, 2, ... for this daemon run; `now`:
+`time.time()`). It is the place for periodic maintenance: sweeping a cache,
+rotating files, reporting. `run` and `run_until_idle` do not emit it.
+
+Listeners run on the daemon's thread between rounds, so keep them quick and
+throttle them yourself; hand long work to a thread. One that raises is logged and
+skipped. A daily sweep:
+
+```python
+last_day = None
+
+def sweep(tick):
+    global last_day
+    day = time.strftime("%Y-%m-%d", time.localtime(tick.now))
+    if day != last_day:  # once a day, and once after each daemon start
+        last_day = day
+        remove_older_than(cache_dir, days=7)
+
+ctx.on("daemon/tick", sweep)
+```
+
 ## Side effects and approvals
 
 Set `side_effect = True` on a step whose effects leave RunSpool: publishing,

{runspool-0.2.0 → runspool-0.2.1}/docs/workflows.md

@@ -42,6 +42,7 @@ concurrency:                         # per-step quota (default 1)
   ingest_file: 4
 
 first_task_id: 1000                  # number new tasks from here (never lowers it)
+default_workflow: local_file         # what `runspool add` uses without --workflow
 
 workflows:
   local_file:
@@ -67,6 +68,9 @@ patch: []                            # insert / modify / disable plugin entries
   (`ready/<id>/`). A relative path is resolved against the config file's
   directory, so the same profile means the same workspace whichever directory a
   command or the daemon starts in.
+- **default_workflow** — the workflow `runspool add` uses when `--workflow` is not
+  given (default `local_file`). It may name a workflow a plugin contributes;
+  `runspool doctor` reports it if no such workflow is defined.
 - **scheduler.max_retries** — the retry budget stamped onto each new task. Set it
   to `0` to make the first failure terminal (it becomes `manual_required`
   immediately) — useful when failures mean "bad input", not "transient glitch".

{runspool-0.2.0 → runspool-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runspool"
-version = "0.2.0"
+version = "0.2.1"
 description = "A local-first CLI workflow engine for reliable personal automation."
 readme = "README.md"
 requires-python = ">=3.11"

{runspool-0.2.0 → runspool-0.2.1}/src/runspool/__init__.py

@@ -9,6 +9,11 @@ readable as JSON for scripts and AI agents.
 
 from __future__ import annotations
 
-__version__ = "0.1.0"
+from importlib import metadata
+
+try:  # the installed distribution is the single source of the version
+    __version__ = metadata.version("runspool")
+except metadata.PackageNotFoundError:  # a bare source tree
+    __version__ = "0+unknown"
 
 __all__ = ["__version__"]

{runspool-0.2.0 → runspool-0.2.1}/src/runspool/cli.py

@@ -105,7 +105,12 @@ def init(
 @app.command()
 def add(
     input: str = typer.Argument(..., help="The task input (e.g. a file path)."),
-    workflow: str = typer.Option("local_file", "--workflow", "-w", help="Workflow name."),
+    workflow: str = typer.Option(
+        None,
+        "--workflow",
+        "-w",
+        help="Workflow name (default: the profile's default_workflow, else local_file).",
+    ),
     name: str = typer.Option(None, "--name", help="Human-readable task name."),
     force: bool = typer.Option(False, "--force", help="Allow a duplicate active task."),
     parent: int = typer.Option(None, "--parent", help="Id of the task this one derives from."),
@@ -121,9 +126,15 @@ def add(
             typer.echo(f"--meta expects KEY=VALUE, got {item!r}")
             raise typer.Exit(1)
         metadata[key] = value
+    ctx = _ctx()
+    if workflow is None:  # only when -w is absent: an empty -w "" is still an error
+        workflow = ctx.config.add_workflow()
+    if workflow not in ctx.config.workflows:
+        typer.echo(f"undefined workflow: {workflow}")
+        raise typer.Exit(1)
     try:
         task_id = commands.add_task(
-            _ctx(),
+            ctx,
             input,
             workflow=workflow,
             name=name,
@@ -136,8 +147,10 @@ def add(
         raise typer.Exit(1) from exc
     except KeyError as exc:
         missing = exc.args[0] if exc.args else exc
-        what = "parent task" if missing == parent else "workflow"
-        typer.echo(f"undefined {what}: {missing}")
+        if parent is not None and missing == parent:
+            typer.echo(f"undefined parent task: {parent}")
+        else:
+            typer.echo(f"error: missing {missing!r}")
         raise typer.Exit(1) from exc
     typer.echo(f"Created task {task_id}")
 

{runspool-0.2.0 → runspool-0.2.1}/src/runspool/config.py

@@ -73,6 +73,9 @@ class AppConfig(BaseModel):
     # Number new tasks from here on (never lowers the numbering). For a database that
     # continues an older system whose task ids are used as keys elsewhere.
     first_task_id: int | None = Field(default=None, ge=1)
+    # The workflow `runspool add` uses when no --workflow is given (default: local_file).
+    # Plugins may contribute it, so it is checked by doctor rather than at load time.
+    default_workflow: str | None = Field(default=None, min_length=1)
     steps: dict[str, StepPluginConfig] = Field(default_factory=dict)
 
     # Directory of the config file (set by load()); used to resolve plugin_paths.
@@ -112,6 +115,10 @@ class AppConfig(BaseModel):
             raise KeyError(f"undefined workflow: {name!r}")
         return WorkflowDef(name=name, steps=self.workflows[name].steps)
 
+    def add_workflow(self) -> str:
+        """The workflow a new task gets when none is named."""
+        return self.default_workflow or "local_file"
+
     def step_quota(self, step: str) -> int:
         return self.concurrency.get(step, 1)
 

{runspool-0.2.0 → runspool-0.2.1}/src/runspool/core/doctor.py

@@ -72,7 +72,15 @@ class DoctorService:
         checks.append(Check("database", db_ok, db_detail))
 
         n_workflows = len(config.workflows)
-        checks.append(Check("workflows", n_workflows > 0, f"{n_workflows} defined"))
+        detail = f"{n_workflows} defined"
+        ok = n_workflows > 0
+        if config.default_workflow is not None:
+            if config.default_workflow in config.workflows:
+                detail += f"; default: {config.default_workflow}"
+            else:
+                ok = False
+                detail += f"; default_workflow {config.default_workflow!r} is not defined"
+        checks.append(Check("workflows", ok, detail))
 
         # Every step referenced by a workflow resolves (built-in or plugin), and every
         # lazily registered step imports. This catches typos and broken plugin imports

{runspool-0.2.0 → runspool-0.2.1}/src/runspool/core/runtime.py

@@ -90,6 +90,7 @@ class RuntimeService:
         self.store = store
         self.steps = steps
         self._startup = startup
+        self._ctx = ctx
         self.gate = Gate(ctx, steps) if ctx is not None else None
 
     def ensure_ready(self) -> None:
@@ -130,8 +131,16 @@ class RuntimeService:
         return Coordinator(store.repo, store.log, registry, runner, pool, self.config)
 
     def build_daemon(self) -> Daemon:
+        """The resident daemon. After each round it emits ``daemon/tick`` with a
+        :class:`~runspool.daemon.DaemonTick`, so plugins can do periodic maintenance
+        (sweep caches, rotate files). Listeners run on the daemon thread: keep them
+        quick, throttle them yourself (``tick.now``), and hand long work to a thread.
+        A listener that raises is logged and skipped. ``run`` / ``run_until_idle``
+        do not emit it: it belongs to the long-running process."""
         self.ensure_ready()
-        return Daemon(self.build_coordinator(), self.config)
+        ctx = self._ctx
+        on_tick = (lambda tick: ctx.emit("daemon/tick", tick)) if ctx is not None else None
+        return Daemon(self.build_coordinator(), self.config, on_tick=on_tick)
 
     def recover(self) -> None:
         any_workflow = next(iter(self.config.workflows))

{runspool-0.2.0 → runspool-0.2.1}/src/runspool/daemon.py

@@ -5,6 +5,9 @@ from __future__ import annotations
 
 import logging
 import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
@@ -26,11 +29,32 @@ def read_pid(pid_file: Path) -> int | None:
         return None
 
 
+@dataclass(frozen=True)
+class DaemonTick:
+    """One daemon round, after its scheduling work: what ``daemon/tick`` carries.
+
+    ``round`` counts from 1 for each daemon run; ``now`` is ``time.time()``.
+    """
+
+    round: int
+    now: float
+
+
 class Daemon:
-    def __init__(self, coordinator: Coordinator, config: Any) -> None:
+    def __init__(
+        self,
+        coordinator: Coordinator,
+        config: Any,
+        *,
+        on_tick: Callable[[DaemonTick], None] | None = None,
+    ) -> None:
         self.coordinator = coordinator
         self.config = config
+        # Called once per round after scheduling (maintenance hooks). It runs on the
+        # daemon's own thread, so it must return quickly.
+        self.on_tick = on_tick
         self._stop = threading.Event()
+        self._round = 0
 
     def recover(self) -> None:
         # Startup recovery: recover_interrupted only changes task_status / lock
@@ -53,6 +77,16 @@ class Daemon:
         self.coordinator.reclaim_stale(timeout)
         self.coordinator.tick()
 
+    def _tick(self) -> None:
+        if self.on_tick is None:
+            return
+        self._round += 1
+        # Maintenance must never stop scheduling: log and carry on.
+        try:
+            self.on_tick(DaemonTick(round=self._round, now=time.time()))
+        except Exception:  # noqa: BLE001 - a broken hook must not kill the daemon
+            logger.exception("daemon maintenance hook failed; continuing")
+
     def request_stop(self) -> None:
         self._stop.set()
 
@@ -70,6 +104,7 @@ class Daemon:
                     self.run_once()
                 except Exception:  # noqa: BLE001 - tolerate transient errors
                     logger.exception("daemon tick failed; continuing")
+                self._tick()
                 self._stop.wait(timeout=interval)
         finally:
             self.coordinator.pool.shutdown(wait=True)

{runspool-0.2.0 → runspool-0.2.1}/tests/test_cli.py

@@ -186,7 +186,7 @@ def test_add_unknown_workflow(tmp_path):
     cfg = _init(tmp_path)
     result = _invoke(cfg, "add", "x", "--workflow", "nope")
     assert result.exit_code == 1
-    assert "undefined workflow" in result.output
+    assert result.output.strip() == "undefined workflow: nope"
 
 
 def test_wake_runs_a_deferred_task_now(tmp_path):
@@ -262,3 +262,52 @@ def test_bad_engine_settings_are_reported_without_echoing_values(tmp_path):
     assert result.exit_code == 1
     assert "max_retries" in result.output and "sekrit" not in result.output
     assert "Traceback" not in result.output
+
+
+def _profile_with_default(tmp_path, default):
+    cfg = tmp_path / "runspool.yaml"
+    cfg.write_text(
+        f"workspace_root: {tmp_path / 'ws'}\n"
+        f"default_workflow: {default}\n"
+        "workflows:\n  notes:\n    steps: [ingest_file, archive]\n",
+        encoding="utf-8",
+    )
+    return cfg
+
+
+def test_add_uses_the_profile_default_workflow(tmp_path):
+    cfg = _profile_with_default(tmp_path, "notes")
+    src = tmp_path / "a.txt"
+    src.write_text("hi", encoding="utf-8")
+    assert _invoke(cfg, "add", str(src)).exit_code == 0
+    assert json.loads(_invoke(cfg, "status", "1", "--json").output)["workflow"] == "notes"
+    doctor = _invoke(cfg, "doctor")
+    assert "default: notes" in doctor.output
+
+
+def test_an_undefined_default_workflow_is_reported(tmp_path):
+    cfg = _profile_with_default(tmp_path, "nope")
+    src = tmp_path / "a.txt"
+    src.write_text("hi", encoding="utf-8")
+    result = _invoke(cfg, "add", str(src))
+    assert result.exit_code == 1 and "undefined workflow: nope" in result.output
+    doctor = _invoke(cfg, "doctor")
+    assert doctor.exit_code == 1
+    assert "default_workflow 'nope' is not defined" in doctor.output
+
+
+def test_without_a_default_add_still_uses_local_file(tmp_path):
+    cfg = _init(tmp_path)
+    src = tmp_path / "a.txt"
+    src.write_text("hi", encoding="utf-8")
+    assert _invoke(cfg, "add", str(src)).exit_code == 0
+    assert json.loads(_invoke(cfg, "status", "1", "--json").output)["workflow"] == "local_file"
+
+
+def test_an_empty_workflow_option_is_an_error_not_the_default(tmp_path):
+    cfg = _profile_with_default(tmp_path, "notes")
+    src = tmp_path / "a.txt"
+    src.write_text("hi", encoding="utf-8")
+    result = _invoke(cfg, "add", str(src), "--workflow", "")
+    assert result.exit_code == 1
+    assert result.output.strip() == "undefined workflow:"

{runspool-0.2.0 → runspool-0.2.1}/tests/test_config.py

@@ -48,3 +48,13 @@ def test_plugin_import_alias_and_base_dir(tmp_path):
     )
     assert cfg.steps["custom"].import_target == "mod:Cls"
     assert cfg.resolved_plugin_paths() == [tmp_path.resolve() / "steps"]
+
+
+def test_package_version_matches_the_project():
+    import tomllib
+    from pathlib import Path
+
+    import runspool
+
+    project = tomllib.loads((Path(__file__).parents[1] / "pyproject.toml").read_text("utf-8"))
+    assert runspool.__version__ == project["project"]["version"]

runspool-0.2.1/tests/test_daemon_tick.py

@@ -0,0 +1,89 @@
+"""The daemon's maintenance hook: ``daemon/tick`` once per round, never fatal."""
+
+from __future__ import annotations
+
+import logging
+import threading
+from types import SimpleNamespace
+
+from runspool.app import load_context
+from runspool.daemon import Daemon, DaemonTick
+
+
+class _Coordinator:
+    def __init__(self, *, fail: bool = False) -> None:
+        self.fail = fail
+        self.ticks = 0
+        self.pool = SimpleNamespace(shutdown=lambda wait=True: None)
+
+    def reclaim_stale(self, timeout):
+        pass
+
+    def tick(self):
+        self.ticks += 1
+        if self.fail:
+            raise RuntimeError("scheduling broke")
+
+
+def _config():
+    return SimpleNamespace(
+        worker_pool=SimpleNamespace(heartbeat_timeout_seconds=60),
+        scheduler=SimpleNamespace(poll_interval_seconds=0),
+    )
+
+
+def _run(daemon: Daemon, *, until) -> None:
+    daemon.recover = lambda: None  # no store here
+    thread = threading.Thread(target=daemon.run, kwargs={"poll_interval_seconds": 0.001})
+    thread.start()
+    for _ in range(2000):
+        if until():
+            break
+        threading.Event().wait(0.001)
+    daemon.request_stop()
+    thread.join(timeout=5)
+    assert not thread.is_alive()
+
+
+def test_each_round_ends_with_a_tick():
+    seen: list[DaemonTick] = []
+    coordinator = _Coordinator()
+    daemon = Daemon(coordinator, _config(), on_tick=seen.append)
+    _run(daemon, until=lambda: len(seen) >= 3)
+    assert [t.round for t in seen[:3]] == [1, 2, 3]
+    assert seen[0].now <= seen[2].now
+    assert coordinator.ticks >= 3
+
+
+def test_a_failing_hook_or_round_does_not_stop_the_daemon(caplog):
+    calls = []
+
+    def hook(tick):
+        calls.append(tick.round)
+        raise ValueError("hook broke")
+
+    with caplog.at_level(logging.ERROR):
+        daemon = Daemon(_Coordinator(fail=True), _config(), on_tick=hook)
+        _run(daemon, until=lambda: len(calls) >= 3)
+    assert calls[:3] == [1, 2, 3]  # the hook still runs after a failed round
+    assert "maintenance hook failed" in caplog.text
+    assert "daemon tick failed" in caplog.text
+
+
+def test_the_runtime_daemon_emits_daemon_tick_to_plugins(tmp_path, caplog):
+    profile = tmp_path / "runspool.yaml"
+    profile.write_text(f"workspace_root: {tmp_path / 'ws'}\n", encoding="utf-8")
+    ctx = load_context(profile)
+    seen = []
+
+    def broken(tick):
+        raise RuntimeError("listener broke")
+
+    ctx.kernel.root.plugin(lambda c, config: c.on("daemon/tick", broken))
+    ctx.kernel.root.plugin(lambda c, config: c.on("daemon/tick", seen.append))
+    daemon = ctx.service("runtime").build_daemon()
+    tick = DaemonTick(round=1, now=0.0)
+    with caplog.at_level(logging.ERROR):
+        daemon.on_tick(tick)
+    assert seen == [tick]  # one listener failing does not starve the others
+    assert "listener broke" in caplog.text

runspool-0.2.0/.github/workflows/publish.yml

@@ -1,28 +0,0 @@
-name: Publish
-
-on:
-  workflow_dispatch:
-  release:
-    types: [published]
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      id-token: write
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v5
-
-      # RunSpool and its official plugin(s). Example plugins are not published.
-      - name: Build distributions
-        run: |
-          uv build --package runspool -o dist
-          uv build --package runspool-wechat -o dist
-
-      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1