workledger-cli 0.7.0__tar.gz → 0.8.0__tar.gz

{workledger_cli-0.7.0 → workledger_cli-0.8.0}/.github/workflows/tests.yml

@@ -37,6 +37,18 @@ jobs:
         env:
           SONAR_HOST_URL: https://sonarcloud.io
 
+      # No unresolved SonarCloud issue on the PR. A code smell leaves the quality gate
+      # green, so this fails the job while the PR has any OPEN or CONFIRMED issue;
+      # ACCEPTED and FALSE_POSITIVE ones pass. Cited from culture-rules (#43) via
+      # culture-library.
+      - name: SonarCloud unresolved issues
+        if: env.SONAR_TOKEN != '' && github.event_name == 'pull_request'
+        env:
+          SONAR_HOST_URL: https://sonarcloud.io
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: python3 scripts/sonar-pr-issues.py
+
   lint:
     runs-on: ubuntu-latest
     permissions:

{workledger_cli-0.7.0 → workledger_cli-0.8.0}/.gitignore

@@ -228,3 +228,6 @@ __marimo__/
 
 # Per-machine skills config (copy from skills.local.yaml.example)
 skills.local.yaml
+
+# workledger ledger (local evidence store)
+.workledger/

{workledger_cli-0.7.0 → workledger_cli-0.8.0}/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0] - 2026-10-27
+
+### Added
+
+- `append` verb: append one JSON entry (agent, action, summary; optional refs, data) to an append-only JSONL ledger; `--stdin` and `--json` supported; id and UTC timestamp are generated.
+- `list` verb: read entries with `--agent`, `--action`, `--since`, `--limit` filters; `--json` emits an array.
+- Ledger location: `$WORKLEDGER_PATH`, default `.workledger/ledger.jsonl` under the git toplevel of the cwd (the cwd itself outside a repo). No edit/update/delete verb exists by design. `.workledger/` is git-ignored.
+- Integrity: appends are complete writes (short writes are retried) and are refused with exit 2 if the file does not end in a newline. `append` rejects NaN/Infinity (also `1e999`), lone surrogates and control characters/newlines in `agent`/`action`/`summary` as user errors (exit 1) before touching disk; `--stdin` on an interactive terminal fails fast (exit 1).
+- `list` streams the ledger (bounded memory with `--limit`), validates every line, and reports non-UTF-8 bytes, non-object lines, missing/malformed fields or timestamps, and duplicate ids as a corrupt ledger (exit 2, with the line number). `--since` is normalised once to UTC milliseconds; text output escapes control characters so an entry cannot forge extra rows.
+- CI: a `SonarCloud unresolved issues` step fails a pull request while it has any OPEN or CONFIRMED SonarCloud issue (ACCEPTED and FALSE_POSITIVE pass), via `scripts/sonar-pr-issues.py` cited from culture-rules through culture-library.
+
 ## [0.7.0] - 2026-08-24
 
 ### Added

{workledger_cli-0.7.0 → workledger_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: workledger-cli
-Version: 0.7.0
+Version: 0.8.0
 Summary: Tracks work in a ledger so agents can prove what they did. An agent records its work as append-only ledger entries, hands the ledger down to subagents, and gets it back with their entries folded in, so the whole tree of work and its results stays traceable and checkable.
 Project-URL: Homepage, https://github.com/agentculture/workledger-cli
 Project-URL: Issues, https://github.com/agentculture/workledger-cli/issues
@@ -50,6 +50,8 @@ uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
 | `explain <path>` | Markdown docs for any noun/verb path. |
 | `overview` | Read-only descriptive snapshot of the agent. |
 | `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
+| `append <json>` | Append one entry (`agent`, `action`, `summary`; optional `refs`, `data`) to the append-only ledger (`$WORKLEDGER_PATH`, default `.workledger/ledger.jsonl` under the git toplevel of the cwd (the cwd itself outside a repo)). `--stdin` reads JSON from stdin. |
+| `list` | Read entries: `--agent`, `--action`, `--since`, `--limit`. |
 | `cli overview` | Describe the CLI surface itself. |
 
 Every command supports `--json`. Results go to stdout, errors/diagnostics to

{workledger_cli-0.7.0 → workledger_cli-0.8.0}/README.md

@@ -33,6 +33,8 @@ uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
 | `explain <path>` | Markdown docs for any noun/verb path. |
 | `overview` | Read-only descriptive snapshot of the agent. |
 | `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
+| `append <json>` | Append one entry (`agent`, `action`, `summary`; optional `refs`, `data`) to the append-only ledger (`$WORKLEDGER_PATH`, default `.workledger/ledger.jsonl` under the git toplevel of the cwd (the cwd itself outside a repo)). `--stdin` reads JSON from stdin. |
+| `list` | Read entries: `--agent`, `--action`, `--since`, `--limit`. |
 | `cli overview` | Describe the CLI surface itself. |
 
 Every command supports `--json`. Results go to stdout, errors/diagnostics to

{workledger_cli-0.7.0 → workledger_cli-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "workledger-cli"
-version = "0.7.0"
+version = "0.8.0"
 description = "Tracks work in a ledger so agents can prove what they did. An agent records its work as append-only ledger entries, hands the ledger down to subagents, and gets it back with their entries folded in, so the whole tree of work and its results stays traceable and checkable."
 readme = "README.md"
 license = "Apache-2.0"

workledger_cli-0.8.0/scripts/sonar-pr-issues.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+# Cited from agentculture/culture-rules@dcddf88 scripts/sonar-pr-issues.py (cite, don't import).
+"""Fail a pull request that has unresolved SonarCloud issues.
+
+SonarCloud's quality gate can pass with open issues on new code (a code smell does not
+turn it red), so CI runs this right after the scan: it waits until SonarCloud's analysis
+of the PR is for the PR's head commit, then lists the PR's issues whose status is OPEN or
+CONFIRMED and exits 1 when there is any. ACCEPTED and FALSE_POSITIVE issues are resolved
+by a person and pass; FIXED ones are gone.
+
+Environment: ``SONAR_HOST_URL`` (the server; defaults to localhost so nothing outside is
+called by accident), ``SONAR_PROJECT_KEY`` (else ``sonar.projectKey`` from
+``sonar-project.properties``), ``PR_NUMBER``, ``HEAD_SHA`` and optionally ``SONAR_TOKEN``.
+Exit codes: 0 no unresolved issue, 1 unresolved issues, 2 the analysis or the API could
+not be read. Standard library only.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import sys
+import time
+import urllib.parse
+import urllib.request
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Any
+
+UNRESOLVED = ("OPEN", "CONFIRMED")
+PAGE_SIZE = 100
+WAIT_S = 300
+POLL_S = 10
+
+Fetch = Callable[[str, Mapping[str, str]], Mapping[str, Any]]
+
+
+def project_key(env: Mapping[str, str], root: Path) -> str:
+    """``SONAR_PROJECT_KEY``, else ``sonar.projectKey`` from ``sonar-project.properties``."""
+    if env.get("SONAR_PROJECT_KEY"):
+        return env["SONAR_PROJECT_KEY"]
+    for line in (root / "sonar-project.properties").read_text().splitlines():
+        name, _, value = line.partition("=")
+        if name.strip() == "sonar.projectKey" and value.strip():
+            return value.strip()
+    raise SystemExit("sonar-pr-issues: no SONAR_PROJECT_KEY and no sonar.projectKey")
+
+
+def http_fetch(host: str, token: str | None) -> Fetch:
+    """A GET of ``host + path`` with ``params``, as JSON (token as basic auth, if any)."""
+
+    def fetch(path: str, params: Mapping[str, str]) -> Mapping[str, Any]:
+        url = f"{host.rstrip('/')}{path}?{urllib.parse.urlencode(params)}"
+        req = urllib.request.Request(url)  # noqa: S310 - the host is the configured server
+        if token:
+            basic = base64.b64encode(f"{token}:".encode()).decode()
+            req.add_header("Authorization", f"Basic {basic}")
+        with urllib.request.urlopen(req, timeout=30) as resp:  # nosec B310
+            return json.load(resp)
+
+    return fetch
+
+
+def analysed_commit(fetch: Fetch, project: str, pr: str) -> str | None:
+    """The commit SonarCloud last analysed for pull request ``pr``, or ``None``."""
+    data = fetch("/api/project_pull_requests/list", {"project": project})
+    for item in data.get("pullRequests") or ():
+        if str(item.get("key")) == pr:
+            commit = item.get("commit") or {}
+            sha = commit.get("sha")
+            return sha if isinstance(sha, str) else None
+    return None
+
+
+def wait_for_analysis(
+    fetch: Fetch,
+    project: str,
+    pr: str,
+    head: str,
+    *,
+    wait_s: float = WAIT_S,
+    poll_s: float = POLL_S,
+    sleep: Callable[[float], None] = time.sleep,
+    clock: Callable[[], float] = time.monotonic,
+) -> bool:
+    """True once the PR's analysis is for ``head``; False when ``wait_s`` runs out."""
+    deadline = clock() + wait_s
+    while True:
+        if analysed_commit(fetch, project, pr) == head:
+            return True
+        if clock() >= deadline:
+            return False
+        sleep(poll_s)
+
+
+def unresolved_issues(fetch: Fetch, project: str, pr: str) -> list[Mapping[str, Any]]:
+    """Every OPEN or CONFIRMED issue of pull request ``pr``, across pages."""
+    out: list[Mapping[str, Any]] = []
+    page = 1
+    while True:
+        data = fetch(
+            "/api/issues/search",
+            {
+                "componentKeys": project,
+                "pullRequest": pr,
+                "issueStatuses": ",".join(UNRESOLVED),
+                "ps": str(PAGE_SIZE),
+                "p": str(page),
+            },
+        )
+        issues = [i for i in data.get("issues") or () if isinstance(i, Mapping)]
+        out.extend(issues)
+        total = data.get("total")
+        if not issues or not isinstance(total, int) or len(out) >= total:
+            return out
+        page += 1
+
+
+def describe(issue: Mapping[str, Any], project: str) -> str:
+    """One line: rule, file and line, severity, message."""
+    component = str(issue.get("component") or "").removeprefix(f"{project}:")
+    line = issue.get("line")
+    where = f"{component}:{line}" if line else component
+    return (
+        f"[{issue.get('rule')}] {where} ({issue.get('severity')}, "
+        f"{issue.get('issueStatus') or issue.get('status')}): {issue.get('message')}"
+    )
+
+
+def main(
+    env: Mapping[str, str] | None = None,
+    fetch: Fetch | None = None,
+    root: Path | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+) -> int:
+    env = os.environ if env is None else env
+    root = Path(__file__).resolve().parents[1] if root is None else root
+    pr, head = env.get("PR_NUMBER", ""), env.get("HEAD_SHA", "")
+    if not pr or not head:
+        print("sonar-pr-issues: PR_NUMBER and HEAD_SHA are required", file=sys.stderr)
+        return 2
+    project = project_key(env, root)
+    if fetch is None:
+        host = env.get("SONAR_HOST_URL") or "http://localhost:9000"
+        fetch = http_fetch(host, env.get("SONAR_TOKEN") or None)
+    try:
+        if not wait_for_analysis(fetch, project, pr, head, sleep=sleep):
+            print(
+                f"sonar-pr-issues: no SonarCloud analysis of PR #{pr} at {head[:12]}",
+                file=sys.stderr,
+            )
+            return 2
+        issues = unresolved_issues(fetch, project, pr)
+    except (OSError, ValueError) as exc:  # URLError is an OSError; bad JSON a ValueError
+        print(f"sonar-pr-issues: SonarCloud could not be read: {exc}", file=sys.stderr)
+        return 2
+    if not issues:
+        print(f"SonarCloud: PR #{pr} has no unresolved issue (accepted ones pass)")
+        return 0
+    print(f"SonarCloud: PR #{pr} has {len(issues)} unresolved issue(s); fix or accept each:")
+    for issue in issues:
+        print(f"  - {describe(issue, project)}")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())