workledger-cli 0.8.0__tar.gz → 0.9.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/CHANGELOG.md +18 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/PKG-INFO +22 -29
- workledger_cli-0.9.0/README.md +54 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/pyproject.toml +1 -1
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/tests/test_cli.py +2 -2
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/tests/test_cli_introspection.py +3 -3
- workledger_cli-0.9.0/tests/test_self_description.py +294 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/uv.lock +1 -1
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/__init__.py +1 -1
- workledger_cli-0.9.0/workledger/_about.py +27 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/__init__.py +9 -10
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_commands/_store.py +11 -2
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_commands/append.py +2 -2
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_commands/cli.py +4 -4
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_commands/doctor.py +2 -2
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_commands/explain.py +2 -2
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_commands/learn.py +34 -21
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_commands/list.py +1 -1
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_commands/overview.py +25 -9
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_commands/whoami.py +4 -3
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_errors.py +1 -1
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/explain/__init__.py +1 -1
- workledger_cli-0.9.0/workledger/explain/catalog.py +182 -0
- workledger_cli-0.8.0/README.md +0 -61
- workledger_cli-0.8.0/workledger/explain/catalog.py +0 -167
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/agent-config/SKILL.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/agent-config/data/backend-fingerprints.yaml +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/agent-config/scripts/show.sh +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/ask-colleague/SKILL.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/ask-colleague/prompts/explore.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/ask-colleague/prompts/review.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/ask-colleague/prompts/write.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/ask-colleague/scripts/ask-colleague.sh +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/assign-to-workforce/SKILL.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/assign-to-workforce/scripts/assign-to-workforce.sh +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/challenge/SKILL.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/cicd/SKILL.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/cicd/scripts/_resolve-nick.sh +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/cicd/scripts/portability-lint.sh +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/cicd/scripts/pr-reply.sh +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/cicd/scripts/pr-status.sh +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/cicd/scripts/workflow.sh +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/communicate/SKILL.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/communicate/scripts/fetch-issues.sh +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/communicate/scripts/mesh-message.sh +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/communicate/scripts/post-comment.sh +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/communicate/scripts/post-issue.sh +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/communicate/scripts/templates/skill-new-brief.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/communicate/scripts/templates/skill-update-brief.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/deviate/SKILL.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/doc-test-alignment/SKILL.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/doc-test-alignment/scripts/check.sh +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/pypi-maintainer/SKILL.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/pypi-maintainer/scripts/switch-source.sh +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/recall/SKILL.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/recall/scripts/recall.sh +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/remember/SKILL.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/remember/scripts/remember.sh +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/run-tests/SKILL.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/run-tests/scripts/test.sh +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/scope/SKILL.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/sonarclaude/SKILL.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/sonarclaude/scripts/sonar.sh +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/spec-to-plan/SKILL.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/spec-to-plan/scripts/spec-to-plan.sh +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/summarize-delivery/SKILL.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/think/SKILL.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/think/scripts/think.sh +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/version-bump/SKILL.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/version-bump/scripts/bump.py +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills.local.yaml.example +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.flake8 +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.github/workflows/publish.yml +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.github/workflows/tests.yml +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.gitignore +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.markdownlint-cli2.yaml +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/AGENTS.colleague.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/CLAUDE.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/LICENSE +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/culture.yaml +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/docs/skill-sources.md +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/scripts/sonar-pr-issues.py +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/sonar-project.properties +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/tests/__init__.py +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/tests/test_ledger.py +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/tests/test_sonar_pr_issues.py +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/__main__.py +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_commands/__init__.py +0 -0
- {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_output.py +0 -0
|
@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
Format follows [Keep a Changelog](https://keepachangelog.com/). This project
|
|
6
6
|
adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [0.9.0] - 2026-11-19
|
|
9
|
+
|
|
10
|
+
### Changed
|
|
11
|
+
|
|
12
|
+
- The argparse `prog` is now `ledger`, the command the package installs, and every invocation the tool prints uses it: `--help` usage lines (`usage: ledger ...`), `--version` (`ledger <version>`), the `learn` text, the `explain` catalog headings and usage blocks, the subjects `ledger cli` (`cli overview`, text and `--json`) and `ledger doctor: ...`, and error hints and remediations (`run 'ledger --help' ...`, `ledger explain ledger`, `ledger append --stdin`). They used to say `workledger-cli <verb>`, which is not an installed command. The package and distribution are still named `workledger-cli`; `explain`, `explain workledger-cli` and `explain ledger` all still resolve to the root entry.
|
|
13
|
+
- `learn --json`: `explain_pointer` is now `ledger explain <path>`, a new `console_script` field holds `ledger`, and `purpose` describes the ledger. `tool` is still `workledger-cli`.
|
|
14
|
+
- `overview` (text and `--json`) has a new last section, `Purpose`, that says what the package is for. `Identity` and `Verbs` keep their positions (indexes 0 and 1).
|
|
15
|
+
- `overview`: the third section is now titled `Repository artifacts` (was `Sibling-pattern artifacts`), and its skills line reads "vendored skills".
|
|
16
|
+
- The root `explain` entry's heading now names both the package and the command: ``# workledger-cli (command: `ledger`)``.
|
|
17
|
+
- README quickstart uses the `ledger` command and shows `append` and `list`; its list of what the repository contains was rewritten against the tree (18 skills, not 11).
|
|
18
|
+
- The one-sentence summary in `--help`, `learn`, `explain` and `overview` is read from the installed distribution's metadata (`workledger/_about.py`), not copied into each.
|
|
19
|
+
|
|
20
|
+
### Fixed
|
|
21
|
+
|
|
22
|
+
- The `--help` description, the `learn` text and JSON, the `explain` root entry and the `overview` docs described the starter this repo was scaffolded from ("a clonable template for AgentCulture mesh agents"). They now describe the package: a work ledger for agents, matching the `pyproject.toml` description.
|
|
23
|
+
- The default ledger path was described as `./.workledger/ledger.jsonl`, and then as "under the git toplevel". `learn`, `explain`, `explain append`, `overview` and the README now state what the store does: `$WORKLEDGER_PATH` when set; otherwise `.workledger/ledger.jsonl` under the nearest ancestor directory that contains `.git` (else the current directory). The store's behaviour did not change.
|
|
24
|
+
- README no longer carries the starter's "Make it your own" rename instructions, and a leftover "register your own noun groups" comment is gone from the parser.
|
|
25
|
+
|
|
8
26
|
## [0.8.0] - 2026-10-27
|
|
9
27
|
|
|
10
28
|
### Added
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: workledger-cli
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.9.0
|
|
4
4
|
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.
|
|
5
5
|
Project-URL: Homepage, https://github.com/agentculture/workledger-cli
|
|
6
6
|
Project-URL: Issues, https://github.com/agentculture/workledger-cli/issues
|
|
@@ -19,25 +19,33 @@ Description-Content-Type: text/markdown
|
|
|
19
19
|
|
|
20
20
|
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.
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
The package and distribution are named `workledger-cli`; the command it
|
|
23
|
+
installs is `ledger`.
|
|
23
24
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
- **
|
|
27
|
-
|
|
28
|
-
`
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
25
|
+
## What is in this repository
|
|
26
|
+
|
|
27
|
+
- **The `ledger` command** (`workledger/`) — two ledger verbs, `append` and
|
|
28
|
+
`list`, over an append-only JSONL file, plus the self-describing verbs
|
|
29
|
+
`whoami`, `learn`, `explain`, `overview`, `doctor` and `cli overview`. The
|
|
30
|
+
package declares no runtime dependencies.
|
|
31
|
+
- **A mesh identity** — `culture.yaml` (`suffix`, `backend: colleague`, `model`)
|
|
32
|
+
and the matching resident prompt file, `AGENTS.colleague.md`.
|
|
33
|
+
- **18 skills** under `.claude/skills/`, vendored cite-don't-import. Where each
|
|
34
|
+
one comes from is recorded in [`docs/skill-sources.md`](docs/skill-sources.md).
|
|
35
|
+
- **Tests and CI** — `tests/` (pytest), and `.github/workflows/tests.yml`, which
|
|
36
|
+
runs the tests, black, isort, flake8, bandit, markdownlint, the `teken`
|
|
37
|
+
rubric gate, a version-bump check, and SonarCloud. `publish.yml` publishes to
|
|
38
|
+
PyPI and TestPyPI with Trusted Publishing.
|
|
33
39
|
|
|
34
40
|
## Quickstart
|
|
35
41
|
|
|
36
42
|
```bash
|
|
37
43
|
uv sync
|
|
38
44
|
uv run pytest -n auto # run the test suite
|
|
39
|
-
uv run
|
|
40
|
-
uv run
|
|
45
|
+
uv run ledger whoami # identity from culture.yaml
|
|
46
|
+
uv run ledger learn # self-teaching prompt (add --json)
|
|
47
|
+
uv run ledger append '{"agent":"a","action":"edit","summary":"did x"}'
|
|
48
|
+
uv run ledger list --agent a # read entries back (add --json)
|
|
41
49
|
uv run teken cli doctor . --strict # the agent-first rubric gate CI runs
|
|
42
50
|
```
|
|
43
51
|
|
|
@@ -50,7 +58,7 @@ uv run teken cli doctor . --strict # the agent-first rubric gate CI runs
|
|
|
50
58
|
| `explain <path>` | Markdown docs for any noun/verb path. |
|
|
51
59
|
| `overview` | Read-only descriptive snapshot of the agent. |
|
|
52
60
|
| `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
|
|
53
|
-
| `append <json>` | Append one entry (`agent`, `action`, `summary`; optional `refs`, `data`) to the append-only ledger (`$WORKLEDGER_PATH
|
|
61
|
+
| `append <json>` | Append one entry (`agent`, `action`, `summary`; optional `refs`, `data`) to the append-only ledger (`$WORKLEDGER_PATH` when set; otherwise `.workledger/ledger.jsonl` under the nearest ancestor directory that contains `.git` (else the current directory)). `--stdin` reads JSON from stdin. |
|
|
54
62
|
| `list` | Read entries: `--agent`, `--action`, `--since`, `--limit`. |
|
|
55
63
|
| `cli overview` | Describe the CLI surface itself. |
|
|
56
64
|
|
|
@@ -58,21 +66,6 @@ Every command supports `--json`. Results go to stdout, errors/diagnostics to
|
|
|
58
66
|
stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
|
|
59
67
|
error, `3+` reserved.
|
|
60
68
|
|
|
61
|
-
## Make it your own
|
|
62
|
-
|
|
63
|
-
1. Rename the package `workledger/` and the `workledger-cli`
|
|
64
|
-
CLI/dist name throughout `pyproject.toml`, the package, `tests/`,
|
|
65
|
-
`sonar-project.properties`, and this `README.md`. The name is hard-coded in
|
|
66
|
-
~100 places, so list every occurrence first — see the `git grep` discovery
|
|
67
|
-
command in [`CLAUDE.md`](CLAUDE.md), the authoritative rename procedure.
|
|
68
|
-
2. Edit `culture.yaml` with your `suffix` and `backend`.
|
|
69
|
-
3. Rewrite `CLAUDE.md` for your agent and run `/init`.
|
|
70
|
-
4. Re-vendor only the skills you need from guildmaster (see
|
|
71
|
-
[`docs/skill-sources.md`](docs/skill-sources.md)).
|
|
72
|
-
|
|
73
|
-
See [`CLAUDE.md`](CLAUDE.md) for the full conventions (version-bump-every-PR,
|
|
74
|
-
the `cicd` PR lane, deploy setup).
|
|
75
|
-
|
|
76
69
|
## License
|
|
77
70
|
|
|
78
71
|
Apache 2.0 — see [`LICENSE`](LICENSE).
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# workledger-cli
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
The package and distribution are named `workledger-cli`; the command it
|
|
6
|
+
installs is `ledger`.
|
|
7
|
+
|
|
8
|
+
## What is in this repository
|
|
9
|
+
|
|
10
|
+
- **The `ledger` command** (`workledger/`) — two ledger verbs, `append` and
|
|
11
|
+
`list`, over an append-only JSONL file, plus the self-describing verbs
|
|
12
|
+
`whoami`, `learn`, `explain`, `overview`, `doctor` and `cli overview`. The
|
|
13
|
+
package declares no runtime dependencies.
|
|
14
|
+
- **A mesh identity** — `culture.yaml` (`suffix`, `backend: colleague`, `model`)
|
|
15
|
+
and the matching resident prompt file, `AGENTS.colleague.md`.
|
|
16
|
+
- **18 skills** under `.claude/skills/`, vendored cite-don't-import. Where each
|
|
17
|
+
one comes from is recorded in [`docs/skill-sources.md`](docs/skill-sources.md).
|
|
18
|
+
- **Tests and CI** — `tests/` (pytest), and `.github/workflows/tests.yml`, which
|
|
19
|
+
runs the tests, black, isort, flake8, bandit, markdownlint, the `teken`
|
|
20
|
+
rubric gate, a version-bump check, and SonarCloud. `publish.yml` publishes to
|
|
21
|
+
PyPI and TestPyPI with Trusted Publishing.
|
|
22
|
+
|
|
23
|
+
## Quickstart
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
uv sync
|
|
27
|
+
uv run pytest -n auto # run the test suite
|
|
28
|
+
uv run ledger whoami # identity from culture.yaml
|
|
29
|
+
uv run ledger learn # self-teaching prompt (add --json)
|
|
30
|
+
uv run ledger append '{"agent":"a","action":"edit","summary":"did x"}'
|
|
31
|
+
uv run ledger list --agent a # read entries back (add --json)
|
|
32
|
+
uv run teken cli doctor . --strict # the agent-first rubric gate CI runs
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## CLI
|
|
36
|
+
|
|
37
|
+
| Verb | What it does |
|
|
38
|
+
|------|--------------|
|
|
39
|
+
| `whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
|
|
40
|
+
| `learn` | Print a structured self-teaching prompt. |
|
|
41
|
+
| `explain <path>` | Markdown docs for any noun/verb path. |
|
|
42
|
+
| `overview` | Read-only descriptive snapshot of the agent. |
|
|
43
|
+
| `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
|
|
44
|
+
| `append <json>` | Append one entry (`agent`, `action`, `summary`; optional `refs`, `data`) to the append-only ledger (`$WORKLEDGER_PATH` when set; otherwise `.workledger/ledger.jsonl` under the nearest ancestor directory that contains `.git` (else the current directory)). `--stdin` reads JSON from stdin. |
|
|
45
|
+
| `list` | Read entries: `--agent`, `--action`, `--since`, `--limit`. |
|
|
46
|
+
| `cli overview` | Describe the CLI surface itself. |
|
|
47
|
+
|
|
48
|
+
Every command supports `--json`. Results go to stdout, errors/diagnostics to
|
|
49
|
+
stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
|
|
50
|
+
error, `3+` reserved.
|
|
51
|
+
|
|
52
|
+
## License
|
|
53
|
+
|
|
54
|
+
Apache 2.0 — see [`LICENSE`](LICENSE).
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "workledger-cli"
|
|
3
|
-
version = "0.
|
|
3
|
+
version = "0.9.0"
|
|
4
4
|
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."
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
license = "Apache-2.0"
|
|
@@ -21,7 +21,7 @@ def test_version_flag(capsys: pytest.CaptureFixture[str]) -> None:
|
|
|
21
21
|
def test_no_args_prints_help(capsys: pytest.CaptureFixture[str]) -> None:
|
|
22
22
|
rc = main([])
|
|
23
23
|
assert rc == 0
|
|
24
|
-
assert "usage:
|
|
24
|
+
assert "usage: ledger" in capsys.readouterr().out
|
|
25
25
|
|
|
26
26
|
|
|
27
27
|
def test_unknown_command_errors(capsys: pytest.CaptureFixture[str]) -> None:
|
|
@@ -97,7 +97,7 @@ def test_explain_json(capsys: pytest.CaptureFixture[str]) -> None:
|
|
|
97
97
|
assert rc == 0
|
|
98
98
|
payload = json.loads(capsys.readouterr().out)
|
|
99
99
|
assert payload["path"] == ["whoami"]
|
|
100
|
-
assert "
|
|
100
|
+
assert "ledger whoami" in payload["markdown"]
|
|
101
101
|
|
|
102
102
|
|
|
103
103
|
def test_explain_unknown_path_errors(capsys: pytest.CaptureFixture[str]) -> None:
|
|
@@ -41,14 +41,14 @@ def test_overview_graceful_on_bad_path(capsys: pytest.CaptureFixture[str]) -> No
|
|
|
41
41
|
def test_cli_overview_text(capsys: pytest.CaptureFixture[str]) -> None:
|
|
42
42
|
rc = main(["cli", "overview"])
|
|
43
43
|
assert rc == 0
|
|
44
|
-
assert "#
|
|
44
|
+
assert "# ledger cli" in capsys.readouterr().out
|
|
45
45
|
|
|
46
46
|
|
|
47
47
|
def test_cli_overview_json_shape(capsys: pytest.CaptureFixture[str]) -> None:
|
|
48
48
|
rc = main(["cli", "overview", "--json"])
|
|
49
49
|
assert rc == 0
|
|
50
50
|
payload = json.loads(capsys.readouterr().out)
|
|
51
|
-
assert payload["subject"] == "
|
|
51
|
+
assert payload["subject"] == "ledger cli"
|
|
52
52
|
assert isinstance(payload["sections"], list)
|
|
53
53
|
|
|
54
54
|
|
|
@@ -77,7 +77,7 @@ def test_cli_overview_unknown_flag_structured_error(
|
|
|
77
77
|
def test_doctor_text(capsys: pytest.CaptureFixture[str]) -> None:
|
|
78
78
|
rc = main(["doctor"])
|
|
79
79
|
assert rc in (0, 1)
|
|
80
|
-
assert "
|
|
80
|
+
assert "ledger doctor" in capsys.readouterr().out
|
|
81
81
|
|
|
82
82
|
|
|
83
83
|
def test_doctor_json_shape(capsys: pytest.CaptureFixture[str]) -> None:
|
|
@@ -0,0 +1,294 @@
|
|
|
1
|
+
"""The package's self-descriptions say what it is: a work ledger for agents.
|
|
2
|
+
|
|
3
|
+
The repo was scaffolded from a mesh-agent starter, and its help text, ``learn``,
|
|
4
|
+
``explain`` and ``overview`` once described that starter instead of the ledger.
|
|
5
|
+
These tests hold every user-facing self-description to the summary in
|
|
6
|
+
``pyproject.toml``, to the command that is actually installed (``ledger``), and
|
|
7
|
+
to what the store really does when it picks the ledger file.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import argparse
|
|
13
|
+
import contextlib
|
|
14
|
+
import json
|
|
15
|
+
import re
|
|
16
|
+
import tomllib
|
|
17
|
+
from importlib.metadata import PackageNotFoundError
|
|
18
|
+
from pathlib import Path
|
|
19
|
+
|
|
20
|
+
import pytest
|
|
21
|
+
|
|
22
|
+
from workledger import _about
|
|
23
|
+
from workledger.cli import _build_parser, main
|
|
24
|
+
from workledger.explain import known_paths
|
|
25
|
+
|
|
26
|
+
_REPO = Path(__file__).resolve().parents[1]
|
|
27
|
+
_PYPROJECT = _REPO / "pyproject.toml"
|
|
28
|
+
_JSON_FLAG = "--json"
|
|
29
|
+
_OVERVIEW = "overview"
|
|
30
|
+
_SECTIONS = "sections"
|
|
31
|
+
|
|
32
|
+
# Phrases left over from the starter this repo was scaffolded from. Whole
|
|
33
|
+
# phrases, not single words, so honest later wording is not refused.
|
|
34
|
+
_LEFTOVER_PHRASES = (
|
|
35
|
+
"clonable template",
|
|
36
|
+
"this template",
|
|
37
|
+
"clone it",
|
|
38
|
+
"rename the package",
|
|
39
|
+
"make it your own",
|
|
40
|
+
"register your own",
|
|
41
|
+
"sibling-pattern",
|
|
42
|
+
)
|
|
43
|
+
|
|
44
|
+
# How the store picks the default ledger file (see ``_store.ledger_path``).
|
|
45
|
+
_PATH_RULE = "nearest ancestor directory that contains .git (else the current directory)"
|
|
46
|
+
_WRONG_PATH_RULE = "git toplevel"
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def _verbs() -> list[str]:
|
|
50
|
+
"""Every top-level verb the parser registers."""
|
|
51
|
+
actions = _build_parser()._actions
|
|
52
|
+
sub = next(a for a in actions if isinstance(a, argparse._SubParsersAction))
|
|
53
|
+
return list(sub.choices)
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
_VERBS = _verbs()
|
|
57
|
+
# The package name followed by a verb: an invocation that is not installed.
|
|
58
|
+
_NOT_INSTALLED = re.compile(r"workledger-cli\s+(?:" + "|".join(map(re.escape, _VERBS)) + r")\b")
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def _pyproject_summary() -> str:
|
|
62
|
+
"""The first sentence of the ``pyproject.toml`` description."""
|
|
63
|
+
with _PYPROJECT.open("rb") as handle:
|
|
64
|
+
description = tomllib.load(handle)["project"]["description"]
|
|
65
|
+
return description.split(". ", 1)[0].rstrip(".") + "."
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def _flat(text: str) -> str:
|
|
69
|
+
"""Lower-case, drop backticks and collapse whitespace (line wrapping is ignored)."""
|
|
70
|
+
return " ".join(text.lower().replace("`", "").split())
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def _run(argv: list[str], capsys: pytest.CaptureFixture[str]) -> str:
|
|
74
|
+
"""Run the CLI and return stdout and stderr together, whatever the exit."""
|
|
75
|
+
with contextlib.suppress(SystemExit):
|
|
76
|
+
main(argv)
|
|
77
|
+
captured = capsys.readouterr()
|
|
78
|
+
return captured.out + captured.err
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def _assert_no_leftovers(text: str, where: str) -> None:
|
|
82
|
+
flat = _flat(text)
|
|
83
|
+
for phrase in _LEFTOVER_PHRASES:
|
|
84
|
+
assert phrase not in flat, f"{where} still carries starter wording: {phrase!r}"
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def _assert_describes_the_ledger(text: str, where: str) -> None:
|
|
88
|
+
assert _flat(_about.summary()) in _flat(text), f"{where} does not carry the summary"
|
|
89
|
+
_assert_no_leftovers(text, where)
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
# --- one source for the summary -------------------------------------------
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def test_summary_matches_pyproject() -> None:
|
|
96
|
+
assert _about.summary() == _pyproject_summary()
|
|
97
|
+
assert _about.summary() == "Tracks work in a ledger so agents can prove what they did."
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def test_summary_fallback_matches_pyproject(monkeypatch: pytest.MonkeyPatch) -> None:
|
|
101
|
+
def _missing(name: str) -> None:
|
|
102
|
+
raise PackageNotFoundError(name)
|
|
103
|
+
|
|
104
|
+
monkeypatch.setattr(_about, "metadata", _missing)
|
|
105
|
+
assert _about.summary() == _pyproject_summary()
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def test_command_is_the_installed_script() -> None:
|
|
109
|
+
with _PYPROJECT.open("rb") as handle:
|
|
110
|
+
scripts = tomllib.load(handle)["project"]["scripts"]
|
|
111
|
+
assert list(scripts) == [_about.COMMAND]
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
# --- every surface carries the summary ------------------------------------
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
@pytest.mark.parametrize(
|
|
118
|
+
"argv",
|
|
119
|
+
[[], ["learn"], ["explain"], ["explain", "workledger-cli"], ["explain", "ledger"], [_OVERVIEW]],
|
|
120
|
+
)
|
|
121
|
+
def test_surface_describes_the_ledger(argv: list[str], capsys: pytest.CaptureFixture[str]) -> None:
|
|
122
|
+
assert main(argv) == 0
|
|
123
|
+
_assert_describes_the_ledger(capsys.readouterr().out, " ".join(argv) or "--help")
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
@pytest.mark.parametrize("argv", [["learn"], ["explain"]])
|
|
127
|
+
def test_surface_says_append_only(argv: list[str], capsys: pytest.CaptureFixture[str]) -> None:
|
|
128
|
+
assert main(argv) == 0
|
|
129
|
+
assert "append-only" in capsys.readouterr().out
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
def test_learn_json_describes_the_ledger(capsys: pytest.CaptureFixture[str]) -> None:
|
|
133
|
+
assert main(["learn", _JSON_FLAG]) == 0
|
|
134
|
+
payload = json.loads(capsys.readouterr().out)
|
|
135
|
+
_assert_describes_the_ledger(payload["purpose"], "learn --json purpose")
|
|
136
|
+
assert payload["console_script"] == _about.COMMAND
|
|
137
|
+
assert payload["explain_pointer"] == "ledger explain <path>"
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
# --- learn keeps what the rubric asks for ---------------------------------
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
def test_learn_text_keeps_the_rubric_topics(capsys: pytest.CaptureFixture[str]) -> None:
|
|
144
|
+
assert main(["learn"]) == 0
|
|
145
|
+
out = capsys.readouterr().out
|
|
146
|
+
assert len(out) >= 200
|
|
147
|
+
for topic in ("Purpose", "Commands", "Exit-code policy", _JSON_FLAG, "explain"):
|
|
148
|
+
assert topic in out
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
@pytest.mark.parametrize("verb", _VERBS)
|
|
152
|
+
def test_learn_text_has_a_row_for_each_verb(verb: str, capsys: pytest.CaptureFixture[str]) -> None:
|
|
153
|
+
assert main(["learn"]) == 0
|
|
154
|
+
row = re.compile(rf"^ ledger {re.escape(verb)}\b.*\S", re.MULTILINE)
|
|
155
|
+
assert row.search(capsys.readouterr().out), f"no command row for {verb!r}"
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
def test_learn_json_lists_each_verb(capsys: pytest.CaptureFixture[str]) -> None:
|
|
159
|
+
assert main(["learn", _JSON_FLAG]) == 0
|
|
160
|
+
payload = json.loads(capsys.readouterr().out)
|
|
161
|
+
listed = {command["path"][0] for command in payload["commands"]}
|
|
162
|
+
assert listed == set(_VERBS)
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
def test_every_verb_has_a_catalog_entry() -> None:
|
|
166
|
+
assert {(verb,) for verb in _VERBS} <= set(known_paths())
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
# --- the invocation is the installed command ------------------------------
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def _user_facing_argvs() -> list[list[str]]:
|
|
173
|
+
argvs: list[list[str]] = [[], ["--help"], ["learn"], ["learn", _JSON_FLAG]]
|
|
174
|
+
argvs.extend([verb, "--help"] for verb in _VERBS)
|
|
175
|
+
argvs.extend(["explain", *path] for path in known_paths())
|
|
176
|
+
argvs.extend(
|
|
177
|
+
[
|
|
178
|
+
[_OVERVIEW],
|
|
179
|
+
[_OVERVIEW, _JSON_FLAG],
|
|
180
|
+
["cli", _OVERVIEW],
|
|
181
|
+
["cli", _OVERVIEW, _JSON_FLAG],
|
|
182
|
+
["doctor"],
|
|
183
|
+
["bogus"],
|
|
184
|
+
["explain", "nonexistent"],
|
|
185
|
+
["explain", "nonexistent", _JSON_FLAG],
|
|
186
|
+
["append", "--bogus"],
|
|
187
|
+
["append"],
|
|
188
|
+
]
|
|
189
|
+
)
|
|
190
|
+
return argvs
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
@pytest.mark.parametrize("argv", _user_facing_argvs(), ids=" ".join)
|
|
194
|
+
def test_no_output_names_an_uninstalled_command(
|
|
195
|
+
argv: list[str], capsys: pytest.CaptureFixture[str]
|
|
196
|
+
) -> None:
|
|
197
|
+
output = _run(argv, capsys)
|
|
198
|
+
assert output.strip()
|
|
199
|
+
assert not _NOT_INSTALLED.search(output), _NOT_INSTALLED.search(output)
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
def test_help_usage_names_the_command(capsys: pytest.CaptureFixture[str]) -> None:
|
|
203
|
+
assert main([]) == 0
|
|
204
|
+
assert "usage: ledger" in capsys.readouterr().out
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
def test_parse_error_hint_names_the_command(capsys: pytest.CaptureFixture[str]) -> None:
|
|
208
|
+
assert "hint: run 'ledger --help'" in _run(["bogus"], capsys)
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
def test_explain_error_hint_names_the_command(capsys: pytest.CaptureFixture[str]) -> None:
|
|
212
|
+
assert "ledger explain ledger" in _run(["explain", "nonexistent"], capsys)
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
def test_readme_names_the_installed_command() -> None:
|
|
216
|
+
readme = (_REPO / "README.md").read_text(encoding="utf-8")
|
|
217
|
+
assert not _NOT_INSTALLED.search(readme)
|
|
218
|
+
_assert_no_leftovers(readme, "README.md")
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
# --- no starter wording anywhere ------------------------------------------
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
@pytest.mark.parametrize("verb", _VERBS)
|
|
225
|
+
def test_verb_help_has_no_starter_wording(verb: str, capsys: pytest.CaptureFixture[str]) -> None:
|
|
226
|
+
_assert_no_leftovers(_run([verb, "--help"], capsys), f"{verb} --help")
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
@pytest.mark.parametrize("path", known_paths(), ids=" ".join)
|
|
230
|
+
def test_catalog_entry_has_no_starter_wording(
|
|
231
|
+
path: tuple[str, ...], capsys: pytest.CaptureFixture[str]
|
|
232
|
+
) -> None:
|
|
233
|
+
assert main(["explain", *path]) == 0
|
|
234
|
+
_assert_no_leftovers(capsys.readouterr().out, f"explain {' '.join(path)}")
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
def test_parser_source_has_no_starter_comment() -> None:
|
|
238
|
+
source = (_REPO / "workledger" / "cli" / "__init__.py").read_text(encoding="utf-8")
|
|
239
|
+
assert "my_noun" not in source
|
|
240
|
+
_assert_no_leftovers(source, "workledger/cli/__init__.py")
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
# --- the default ledger path is described as the store resolves it --------
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
@pytest.mark.parametrize(
|
|
247
|
+
"argv",
|
|
248
|
+
[["learn"], ["explain"], ["explain", "append"], [_OVERVIEW], [_OVERVIEW, _JSON_FLAG]],
|
|
249
|
+
)
|
|
250
|
+
def test_default_path_rule_is_stated(argv: list[str], capsys: pytest.CaptureFixture[str]) -> None:
|
|
251
|
+
assert main(argv) == 0
|
|
252
|
+
flat = _flat(capsys.readouterr().out)
|
|
253
|
+
assert _PATH_RULE in flat
|
|
254
|
+
assert "$workledger_path" in flat
|
|
255
|
+
assert _WRONG_PATH_RULE not in flat
|
|
256
|
+
|
|
257
|
+
|
|
258
|
+
def test_readme_states_the_default_path_rule() -> None:
|
|
259
|
+
flat = _flat((_REPO / "README.md").read_text(encoding="utf-8"))
|
|
260
|
+
assert _PATH_RULE in flat
|
|
261
|
+
assert _WRONG_PATH_RULE not in flat
|
|
262
|
+
|
|
263
|
+
|
|
264
|
+
# --- overview --------------------------------------------------------------
|
|
265
|
+
|
|
266
|
+
|
|
267
|
+
def _overview_sections(capsys: pytest.CaptureFixture[str]) -> list[dict[str, object]]:
|
|
268
|
+
assert main([_OVERVIEW, _JSON_FLAG]) == 0
|
|
269
|
+
return json.loads(capsys.readouterr().out)[_SECTIONS]
|
|
270
|
+
|
|
271
|
+
|
|
272
|
+
def test_overview_json_keeps_identity_first(capsys: pytest.CaptureFixture[str]) -> None:
|
|
273
|
+
titles = [section["title"] for section in _overview_sections(capsys)]
|
|
274
|
+
assert titles == ["Identity", "Verbs", "Repository artifacts", "Purpose"]
|
|
275
|
+
|
|
276
|
+
|
|
277
|
+
def test_overview_json_purpose_describes_the_ledger(capsys: pytest.CaptureFixture[str]) -> None:
|
|
278
|
+
purpose = _overview_sections(capsys)[-1]
|
|
279
|
+
_assert_describes_the_ledger(json.dumps(purpose), "overview --json purpose")
|
|
280
|
+
|
|
281
|
+
|
|
282
|
+
def test_overview_artifacts_exist(capsys: pytest.CaptureFixture[str]) -> None:
|
|
283
|
+
artifacts = _overview_sections(capsys)[2]
|
|
284
|
+
assert artifacts["items"]
|
|
285
|
+
for item in artifacts["items"]:
|
|
286
|
+
names = str(item).split(" — ", 1)[0]
|
|
287
|
+
for name in names.split(" + "):
|
|
288
|
+
assert (_REPO / name).exists(), f"overview names {name!r}, which is not in the repo"
|
|
289
|
+
|
|
290
|
+
|
|
291
|
+
def test_readme_skill_count_matches_the_tree() -> None:
|
|
292
|
+
readme = (_REPO / "README.md").read_text(encoding="utf-8")
|
|
293
|
+
skills = [p for p in (_REPO / ".claude" / "skills").iterdir() if (p / "SKILL.md").is_file()]
|
|
294
|
+
assert f"{len(skills)} skills" in readme
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
"""What this package calls itself: one source for every self-description.
|
|
2
|
+
|
|
3
|
+
The distribution is ``workledger-cli``; the command it installs is ``ledger``.
|
|
4
|
+
The one-sentence summary comes from the installed distribution's metadata (the
|
|
5
|
+
``description`` in ``pyproject.toml``), so the help text, ``learn``, ``explain``
|
|
6
|
+
and ``overview`` cannot drift from it.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
from importlib.metadata import PackageNotFoundError, metadata
|
|
12
|
+
|
|
13
|
+
DISTRIBUTION = "workledger-cli"
|
|
14
|
+
COMMAND = "ledger"
|
|
15
|
+
|
|
16
|
+
# Used only when the distribution's metadata cannot be read.
|
|
17
|
+
_FALLBACK_SUMMARY = "Tracks work in a ledger so agents can prove what they did."
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def summary() -> str:
|
|
21
|
+
"""The first sentence of the distribution's Summary, ending in a full stop."""
|
|
22
|
+
try:
|
|
23
|
+
text = metadata(DISTRIBUTION)["Summary"]
|
|
24
|
+
except PackageNotFoundError:
|
|
25
|
+
return _FALLBACK_SUMMARY
|
|
26
|
+
first = (text or "").split(". ", 1)[0].strip().rstrip(".")
|
|
27
|
+
return f"{first}." if first else _FALLBACK_SUMMARY
|
|
@@ -1,9 +1,10 @@
|
|
|
1
|
-
"""Unified CLI entry point for workledger-cli.
|
|
1
|
+
"""Unified CLI entry point for workledger-cli (the ``ledger`` command).
|
|
2
2
|
|
|
3
|
-
The
|
|
4
|
-
``doctor``) are registered
|
|
5
|
-
alongside the ``cli`` noun group.
|
|
6
|
-
``register()`` functions following
|
|
3
|
+
The ledger verbs (``append``, ``list``) and the agent-first global verbs
|
|
4
|
+
(``whoami``, ``learn``, ``explain``, ``overview``, ``doctor``) are registered
|
|
5
|
+
here under :mod:`workledger.cli._commands`, alongside the ``cli`` noun group.
|
|
6
|
+
Future noun groups register via their own ``register()`` functions following
|
|
7
|
+
the same pattern.
|
|
7
8
|
|
|
8
9
|
Error propagation contract
|
|
9
10
|
--------------------------
|
|
@@ -25,6 +26,7 @@ import argparse
|
|
|
25
26
|
import sys
|
|
26
27
|
|
|
27
28
|
from workledger import __version__
|
|
29
|
+
from workledger._about import COMMAND, DISTRIBUTION, summary
|
|
28
30
|
from workledger.cli._errors import EXIT_USER_ERROR, CliError
|
|
29
31
|
from workledger.cli._output import emit_error
|
|
30
32
|
|
|
@@ -72,8 +74,8 @@ def _build_parser() -> argparse.ArgumentParser:
|
|
|
72
74
|
from workledger.cli._commands import whoami as _whoami_cmd
|
|
73
75
|
|
|
74
76
|
parser = _CliArgumentParser(
|
|
75
|
-
prog=
|
|
76
|
-
description="
|
|
77
|
+
prog=COMMAND,
|
|
78
|
+
description=f"{summary()} (package {DISTRIBUTION}, command {COMMAND})",
|
|
77
79
|
)
|
|
78
80
|
parser.add_argument(
|
|
79
81
|
"--version",
|
|
@@ -92,9 +94,6 @@ def _build_parser() -> argparse.ArgumentParser:
|
|
|
92
94
|
_append_cmd.register(sub)
|
|
93
95
|
_list_cmd.register(sub)
|
|
94
96
|
_cli_group.register(sub)
|
|
95
|
-
# Register your own noun groups here:
|
|
96
|
-
# from workledger.cli._commands import my_noun as _my_noun_group
|
|
97
|
-
# _my_noun_group.register(sub)
|
|
98
97
|
|
|
99
98
|
return parser
|
|
100
99
|
|
|
@@ -27,6 +27,13 @@ INPUT_FIELDS = frozenset(REQUIRED_FIELDS) | {"refs", "data"}
|
|
|
27
27
|
GENERATED_FIELDS = frozenset({"id", "timestamp"})
|
|
28
28
|
UTC_OFFSET = "+00:00"
|
|
29
29
|
|
|
30
|
+
# How :func:`ledger_path` picks the file when ``$WORKLEDGER_PATH`` is unset. The
|
|
31
|
+
# one wording every self-description (learn, explain, overview) repeats.
|
|
32
|
+
DEFAULT_LOCATION_RULE = (
|
|
33
|
+
f"{DEFAULT_PATH.as_posix()} under the nearest ancestor directory that contains .git "
|
|
34
|
+
"(else the current directory)"
|
|
35
|
+
)
|
|
36
|
+
|
|
30
37
|
|
|
31
38
|
# Fixed-format UTC timestamps (what ``now_utc`` writes); lexicographic order == time order.
|
|
32
39
|
TIMESTAMP_RE = re.compile(
|
|
@@ -45,8 +52,10 @@ def _git_toplevel(start: Path) -> Path | None:
|
|
|
45
52
|
def ledger_path() -> Path:
|
|
46
53
|
"""Resolve the ledger file.
|
|
47
54
|
|
|
48
|
-
``$WORKLEDGER_PATH`` wins
|
|
49
|
-
|
|
55
|
+
A non-empty ``$WORKLEDGER_PATH`` wins and is used as given (a relative value
|
|
56
|
+
is relative to the cwd). Otherwise the file is ``.workledger/ledger.jsonl``
|
|
57
|
+
under the nearest directory that contains a ``.git`` entry, searching from
|
|
58
|
+
the cwd itself upwards; with no such directory, under the cwd.
|
|
50
59
|
"""
|
|
51
60
|
env = os.environ.get(ENV_PATH)
|
|
52
61
|
if env:
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
"""``
|
|
1
|
+
"""``ledger append`` — append one entry to the ledger (the only write verb)."""
|
|
2
2
|
|
|
3
3
|
from __future__ import annotations
|
|
4
4
|
|
|
@@ -32,7 +32,7 @@ def cmd_append(args: argparse.Namespace) -> int:
|
|
|
32
32
|
raise CliError(
|
|
33
33
|
code=EXIT_USER_ERROR,
|
|
34
34
|
message="--stdin was given but stdin is an interactive terminal",
|
|
35
|
-
remediation="pipe the entry in (echo '{...}' |
|
|
35
|
+
remediation="pipe the entry in (echo '{...}' | ledger append --stdin)",
|
|
36
36
|
)
|
|
37
37
|
text = sys.stdin.read() if args.stdin else args.entry
|
|
38
38
|
try:
|