pubcheck 0.0.2__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.
@@ -0,0 +1,43 @@
1
+ # wads CI — calls the reusable workflow hosted in i2mint/wads.
2
+ #
3
+ # All configuration comes from this repo's pyproject.toml [tool.wads.ci.*].
4
+ # To customize the workflow itself (rare), replace this file with the
5
+ # full inline template `wads/data/github_ci_uv.yml` from i2mint/wads.
6
+ #
7
+ # Pinning: `@master` floats with wads. If you need version stability for
8
+ # a release-sensitive repo, change `@master` to a wads tag (e.g. `@0.2.15`;
9
+ # tags have no `v` prefix). A stub whose `secrets:` block passes the JSON
10
+ # transport (the default below) needs a tag from a release after 0.2.14 —
11
+ # older tags don't declare that secret and GitHub then rejects the
12
+ # workflow at parse time.
13
+ # CI failure does not block a published release — it blocks the publish
14
+ # step itself — so floating master is generally safe.
15
+ #
16
+ # Permissions: GitHub validates that the caller grants AT LEAST the
17
+ # permissions any job in the called workflow requests — at workflow-parse
18
+ # time, not at run-time, even if the job would be skipped via `if:`.
19
+ # The reusable workflow needs:
20
+ # contents: write for the publish job's version-bump push-back
21
+ # and for the github-pages job's gh-pages branch push
22
+ # pages: write for the github-pages job's REST API Pages config
23
+ # Both default to `write` on org-account GITHUB_TOKEN and need to be
24
+ # granted explicitly on personal-account callers (where the default is
25
+ # read-only). No `id-token: write` needed — the publish-github-pages
26
+ # action uses peaceiris/actions-gh-pages (branch-based) + REST API,
27
+ # not the OIDC `actions/deploy-pages` flow.
28
+ name: Continuous Integration
29
+ on: [push, pull_request]
30
+ jobs:
31
+ ci:
32
+ uses: i2mint/wads/.github/workflows/uv-ci.yml@master
33
+ permissions:
34
+ contents: write
35
+ pages: write
36
+ # Transport (NAMED, legacy): explicitly passes only the secrets
37
+ # listed below (PYPI_PASSWORD + those declared in
38
+ # [tool.wads.ci.env]). Every name must be in the frozen wads
39
+ # superset (wads/ci_secrets.py) or GitHub rejects the workflow
40
+ # at parse time. The default JSON transport has no such limit;
41
+ # regenerate with `wads-migrate ci-to-stub` to switch.
42
+ secrets:
43
+ PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
@@ -0,0 +1,10 @@
1
+ __pycache__/
2
+ *.egg-info/
3
+ .pytest_cache/
4
+ .ruff_cache/
5
+ dist/
6
+ build/
7
+ .venv/
8
+ .coverage
9
+ coverage.xml
10
+ .claude/handoffs/
pubcheck-0.0.2/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Thor Whalen
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,90 @@
1
+ Metadata-Version: 2.5
2
+ Name: pubcheck
3
+ Version: 0.0.2
4
+ Summary: One publication check for every writer: is this text fit for a public repository? Personal names, the owner's own matters, private references, credentials and @mentions, failing closed when nobody is watching.
5
+ Project-URL: Homepage, https://github.com/thorwhalen/pubcheck
6
+ Project-URL: Repository, https://github.com/thorwhalen/pubcheck
7
+ Project-URL: Documentation, https://thorwhalen.github.io/pubcheck
8
+ Project-URL: Issues, https://github.com/thorwhalen/pubcheck/issues
9
+ Author: Thor Whalen
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: agents,claude-code,github,guard,privacy,publication
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: POSIX
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Topic :: Security
19
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
20
+ Requires-Python: >=3.11
21
+ Requires-Dist: openloops
22
+ Provides-Extra: correspond
23
+ Requires-Dist: correspond; extra == 'correspond'
24
+ Provides-Extra: dev
25
+ Requires-Dist: correspond; extra == 'dev'
26
+ Requires-Dist: pytest-cov>=4.0; extra == 'dev'
27
+ Requires-Dist: pytest>=7.0; extra == 'dev'
28
+ Requires-Dist: ruff>=0.1.0; extra == 'dev'
29
+ Description-Content-Type: text/markdown
30
+
31
+ # pubcheck
32
+
33
+ One publication check for every writer: is this text fit for the repository it is about to be published to?
34
+
35
+ ```bash
36
+ pip install pubcheck
37
+ printf '%s' "$BODY" | public-text-guard check --repo octo/app --unattended
38
+ # exit 0 pass, 1 flag, 2 unavailable; one JSON line naming the categories, never the text
39
+ ```
40
+
41
+ ```python
42
+ from pubcheck import check
43
+
44
+ v = check("As the owner asked, we fixed it.", repo="octo/app")
45
+ v.decision, v.categories # ('flag', ['owner-relation'])
46
+ ```
47
+
48
+ A private target passes untouched. A public one, or one whose visibility is unknown, is scanned for:
49
+
50
+ - `registry`: names from the owner's acquaint records that a public reader may not see (`acquaint disclosure --audience '{"scope": "public"}'`);
51
+ - `owner-relation`: the owner's own preferences, corrections or relations ("the operator stated", "my agents");
52
+ - `private-ref`: repos known to be private, private companions, this machine's home folder, and your own `private_patterns`;
53
+ - `session-link`: Claude session links;
54
+ - `credential`: credential-shaped strings (the patterns of `openloops.egress`);
55
+ - `mention`: `@login` and `@org/team` outside code, for an **unattended** writer only, since a mention notifies a person.
56
+
57
+ ## Attended and unattended writers
58
+
59
+ An attended writer (an agent session someone is driving) proceeds without the registry when acquaint cannot be asked, and the gap is logged. An unattended writer (a connector, a scheduled job, anything that posts with nobody reading first) fails closed: a missing registry, a lookup out of time or any error is `unavailable` (exit 2), and the text must be held, never posted.
60
+
61
+ ## Three ways in, one check
62
+
63
+ - **Python**: `pubcheck.check(text, repo=..., title=..., unattended=...)` returns a `Verdict`.
64
+ - **CLI**: `public-text-guard check --repo OWNER/REPO [--unattended] [--title T] [--hold TARGET] [--terms]`, the text on stdin. `--terms` adds the matched terms, for a local author who has to reword; `--hold` files a held post as a desk item.
65
+ - **correspond**: at the top of `~/.config/correspond/config.toml`, `before_send = "pubcheck.correspond:before_send"`. Every write to a public audience is checked unattended; a held one raises correspond's `NeedsApproval` with the categories, and on a real send (not a dry run) becomes a desk item.
66
+
67
+ ## Held posts become desk items
68
+
69
+ With `hold_repo` set, a held post is filed as an issue in that private repo with the label the desk reads (`hold_label`, default `escalate`): the target, the title, the text (credential-shaped strings redacted) and the categories, so it can be published as is, edited or dropped. The hold repo's visibility is asked of GitHub just before filing, and nothing is copied to a repo that is not private. The same text held twice is filed once. With no `hold_repo`, the post is still held; only the desk item is missing.
70
+
71
+ ## Settings
72
+
73
+ `~/.config/pubcheck/config.toml` (`$PUBCHECK_CONFIG` names another file), then environment variables, then keyword arguments:
74
+
75
+ | key | env | default |
76
+ |---|---|---|
77
+ | `hold_repo` | `PUBCHECK_HOLD_REPO` | unset (no desk item) |
78
+ | `hold_label` | `PUBCHECK_HOLD_LABEL` | `escalate` |
79
+ | `budget_seconds` | `PUBCHECK_BUDGET_SECONDS` | `12` |
80
+ | `private_owner` | `PUBCHECK_PRIVATE_OWNER` | unset: the account whose `<owner>/_<name>` repos are private companions |
81
+ | `private_issues` | `PUBCHECK_PRIVATE_ISSUES` | unset: where context with no companion goes |
82
+ | `private_patterns` | (config only) | none: regexes for private references, such as working folders |
83
+
84
+ ## Caches and log
85
+
86
+ Visibility comes from a cache shared with other tools (`~/.cache/priv/repo_visibility/`), then `gh repo view`. The vocabulary is cached an hour in `~/.cache/public-text-guard/`. Decisions worth keeping go to `~/.local/state/public-text-guard/events.jsonl` (mode 0600): categories, repo, writer, a short hash of the text, an error's type and an override's reason; never the text or the matched terms.
87
+
88
+ ## System requirements
89
+
90
+ `gh` (authenticated) for visibility lookups and desk items; `acquaint` for the registry. Without `gh`, visibility is unknown and so public; without `acquaint`, an unattended check is unavailable.
@@ -0,0 +1,60 @@
1
+ # pubcheck
2
+
3
+ One publication check for every writer: is this text fit for the repository it is about to be published to?
4
+
5
+ ```bash
6
+ pip install pubcheck
7
+ printf '%s' "$BODY" | public-text-guard check --repo octo/app --unattended
8
+ # exit 0 pass, 1 flag, 2 unavailable; one JSON line naming the categories, never the text
9
+ ```
10
+
11
+ ```python
12
+ from pubcheck import check
13
+
14
+ v = check("As the owner asked, we fixed it.", repo="octo/app")
15
+ v.decision, v.categories # ('flag', ['owner-relation'])
16
+ ```
17
+
18
+ A private target passes untouched. A public one, or one whose visibility is unknown, is scanned for:
19
+
20
+ - `registry`: names from the owner's acquaint records that a public reader may not see (`acquaint disclosure --audience '{"scope": "public"}'`);
21
+ - `owner-relation`: the owner's own preferences, corrections or relations ("the operator stated", "my agents");
22
+ - `private-ref`: repos known to be private, private companions, this machine's home folder, and your own `private_patterns`;
23
+ - `session-link`: Claude session links;
24
+ - `credential`: credential-shaped strings (the patterns of `openloops.egress`);
25
+ - `mention`: `@login` and `@org/team` outside code, for an **unattended** writer only, since a mention notifies a person.
26
+
27
+ ## Attended and unattended writers
28
+
29
+ An attended writer (an agent session someone is driving) proceeds without the registry when acquaint cannot be asked, and the gap is logged. An unattended writer (a connector, a scheduled job, anything that posts with nobody reading first) fails closed: a missing registry, a lookup out of time or any error is `unavailable` (exit 2), and the text must be held, never posted.
30
+
31
+ ## Three ways in, one check
32
+
33
+ - **Python**: `pubcheck.check(text, repo=..., title=..., unattended=...)` returns a `Verdict`.
34
+ - **CLI**: `public-text-guard check --repo OWNER/REPO [--unattended] [--title T] [--hold TARGET] [--terms]`, the text on stdin. `--terms` adds the matched terms, for a local author who has to reword; `--hold` files a held post as a desk item.
35
+ - **correspond**: at the top of `~/.config/correspond/config.toml`, `before_send = "pubcheck.correspond:before_send"`. Every write to a public audience is checked unattended; a held one raises correspond's `NeedsApproval` with the categories, and on a real send (not a dry run) becomes a desk item.
36
+
37
+ ## Held posts become desk items
38
+
39
+ With `hold_repo` set, a held post is filed as an issue in that private repo with the label the desk reads (`hold_label`, default `escalate`): the target, the title, the text (credential-shaped strings redacted) and the categories, so it can be published as is, edited or dropped. The hold repo's visibility is asked of GitHub just before filing, and nothing is copied to a repo that is not private. The same text held twice is filed once. With no `hold_repo`, the post is still held; only the desk item is missing.
40
+
41
+ ## Settings
42
+
43
+ `~/.config/pubcheck/config.toml` (`$PUBCHECK_CONFIG` names another file), then environment variables, then keyword arguments:
44
+
45
+ | key | env | default |
46
+ |---|---|---|
47
+ | `hold_repo` | `PUBCHECK_HOLD_REPO` | unset (no desk item) |
48
+ | `hold_label` | `PUBCHECK_HOLD_LABEL` | `escalate` |
49
+ | `budget_seconds` | `PUBCHECK_BUDGET_SECONDS` | `12` |
50
+ | `private_owner` | `PUBCHECK_PRIVATE_OWNER` | unset: the account whose `<owner>/_<name>` repos are private companions |
51
+ | `private_issues` | `PUBCHECK_PRIVATE_ISSUES` | unset: where context with no companion goes |
52
+ | `private_patterns` | (config only) | none: regexes for private references, such as working folders |
53
+
54
+ ## Caches and log
55
+
56
+ Visibility comes from a cache shared with other tools (`~/.cache/priv/repo_visibility/`), then `gh repo view`. The vocabulary is cached an hour in `~/.cache/public-text-guard/`. Decisions worth keeping go to `~/.local/state/public-text-guard/events.jsonl` (mode 0600): categories, repo, writer, a short hash of the text, an error's type and an override's reason; never the text or the matched terms.
57
+
58
+ ## System requirements
59
+
60
+ `gh` (authenticated) for visibility lookups and desk items; `acquaint` for the registry. Without `gh`, visibility is unknown and so public; without `acquaint`, an unattended check is unavailable.
@@ -0,0 +1,28 @@
1
+ """pubcheck: one publication check for every writer.
2
+
3
+ Is this text fit for the repository it is about to be published to? A private target
4
+ passes; a public (or unknown) one is scanned for names from the owner's acquaint records,
5
+ the owner's own matters ("the operator stated"), private references, session links,
6
+ credentials, and, for an unattended writer, @mentions. An unattended writer fails closed.
7
+
8
+ >>> from pubcheck import check
9
+ >>> check("Fixed the parser.", repo="octo/app", public=True, log=False).decision
10
+ 'pass'
11
+
12
+ Three ways in, one check: :func:`check` in Python, ``public-text-guard check`` on the
13
+ command line (exit 0 pass, 1 flag, 2 unavailable), and
14
+ ``pubcheck.correspond:before_send`` as correspond's ``before_send``.
15
+ """
16
+
17
+ from pubcheck.core import Verdict, check
18
+ from pubcheck.detectors import DETECTORS, UNATTENDED_DETECTORS, findings
19
+ from pubcheck.hold import file_hold
20
+
21
+ __all__ = [
22
+ "DETECTORS",
23
+ "UNATTENDED_DETECTORS",
24
+ "Verdict",
25
+ "check",
26
+ "file_hold",
27
+ "findings",
28
+ ]
@@ -0,0 +1,106 @@
1
+ """The command line: ``public-text-guard check --repo OWNER/REPO [--unattended]``, the text on stdin.
2
+
3
+ Exit 0 pass (or override), 1 flag, 2 unavailable; one JSON object on stdout naming the
4
+ decision and the categories, never the text (the matched terms only with ``--terms``, for a
5
+ local author who has to reword). ``--unattended`` is for a writer nobody reads before the
6
+ post goes out: @mentions are held, and a missing registry or any failure is ``unavailable``.
7
+ ``--hold TARGET`` (unattended) also files a held post as a desk item and adds its URL to
8
+ the JSON as ``desk_item``.
9
+
10
+ Usage from a script::
11
+
12
+ printf '%s' "$BODY" | public-text-guard check --repo octo/app --unattended
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import argparse
18
+ import json
19
+ import sys
20
+
21
+
22
+ def _parser() -> argparse.ArgumentParser:
23
+ p = argparse.ArgumentParser(
24
+ prog="public-text-guard", description=__doc__.splitlines()[0]
25
+ )
26
+ sub = p.add_subparsers(dest="command", required=True)
27
+ c = sub.add_parser("check", help="check the text on stdin for publication to --repo")
28
+ c.add_argument("--repo", help="OWNER/REPO the text goes to (none: presumed public)")
29
+ c.add_argument(
30
+ "--repo-dir",
31
+ help="a checkout whose origin is the target, when --repo is not given",
32
+ )
33
+ c.add_argument("--title", help="a title published with the text")
34
+ c.add_argument(
35
+ "--unattended",
36
+ action="store_true",
37
+ help="nobody reads it first: fail closed, hold @mentions",
38
+ )
39
+ c.add_argument(
40
+ "--public",
41
+ action="store_true",
42
+ help="the target is known to be public: skip the lookup",
43
+ )
44
+ c.add_argument(
45
+ "--surface",
46
+ default="cli",
47
+ help="what posts it (git commit, gh issue create…), for the log",
48
+ )
49
+ c.add_argument(
50
+ "--override", help="publish despite findings, for this reason (logged)"
51
+ )
52
+ c.add_argument(
53
+ "--terms", action="store_true", help="include the matched terms (local use only)"
54
+ )
55
+ c.add_argument(
56
+ "--hold",
57
+ metavar="TARGET",
58
+ help="on a hold, file a desk item for TARGET (e.g. github:o/r)",
59
+ )
60
+ c.add_argument("--budget", type=float, help="seconds for every lookup together")
61
+ c.add_argument("--session", help="a session id for the log")
62
+ return p
63
+
64
+
65
+ def main(argv=None) -> int:
66
+ """Run the CLI; returns the exit code (0 pass, 1 flag, 2 unavailable)."""
67
+ args = _parser().parse_args(argv)
68
+ try:
69
+ from pubcheck.core import check
70
+
71
+ text = sys.stdin.read()
72
+ verdict = check(
73
+ text,
74
+ repo=args.repo,
75
+ repo_dir=args.repo_dir,
76
+ title=args.title,
77
+ unattended=args.unattended,
78
+ public=True if args.public else None,
79
+ surface=args.surface,
80
+ override=args.override,
81
+ budget=args.budget,
82
+ writer="cli",
83
+ context={"session": args.session} if args.session else None,
84
+ )
85
+ out = verdict.to_json(terms=args.terms)
86
+ if args.hold and verdict.held:
87
+ from pubcheck.hold import file_hold
88
+
89
+ filed = file_hold(verdict, target=args.hold, text=text, title=args.title)
90
+ out["desk_item"] = filed.get("url") or f"not filed: {filed.get('reason')}"
91
+ print(json.dumps(out))
92
+ return verdict.exit_code
93
+ except Exception as error: # the check could not be made
94
+ print(
95
+ json.dumps(
96
+ {
97
+ "decision": "unavailable",
98
+ "reason": f"the check failed ({type(error).__name__})",
99
+ }
100
+ )
101
+ )
102
+ return 2
103
+
104
+
105
+ if __name__ == "__main__":
106
+ raise SystemExit(main())
@@ -0,0 +1,157 @@
1
+ """What every part of the check shares: the time budget, private files, the settings and the event log.
2
+
3
+ **The budget.** Every lookup (``gh``, ``acquaint``, ``git``) runs inside one
4
+ :class:`Budget`, so a check decides within its deadline instead of being killed by its
5
+ caller. Out of time, a lookup answers ``None`` (unknown), and the caller decides what
6
+ unknown means: presumed public for visibility, unavailable for the registry.
7
+
8
+ **Settings.** One mapping, read from ``~/.config/pubcheck/config.toml``
9
+ (``$PUBCHECK_CONFIG`` names another file), with environment variables over it, and keyword
10
+ arguments over both at each call site. The keys are in :data:`DFLT_SETTINGS`.
11
+
12
+ **The log.** ``~/.local/state/public-text-guard/events.jsonl`` (mode 0600,
13
+ ``$PUBLIC_TEXT_GUARD_STATE_DIR``), one JSON object per decision worth keeping: never the
14
+ text and never the matched terms, only the categories, the repo, the writer, a short hash
15
+ of the text (so two events about the same text can be paired), an error's type, and an
16
+ override's reason as its author wrote it.
17
+
18
+ >>> b = Budget(0)
19
+ >>> b.run(["true"]) is None # no time left: no subprocess at all
20
+ True
21
+ """
22
+
23
+ from __future__ import annotations
24
+
25
+ import hashlib
26
+ import json
27
+ import os
28
+ import subprocess
29
+ import time
30
+ from collections.abc import Mapping
31
+ from pathlib import Path
32
+
33
+ import tomllib
34
+
35
+ BUDGET_SECONDS = 12.0
36
+ MAX_TEXT = 70_000 # characters; GitHub caps a body at 65,536, and longer is not checked
37
+ LOOKUP_TIMEOUT = 8.0
38
+ CACHE_DIR_ENV = "PUBLIC_TEXT_GUARD_CACHE_DIR"
39
+ CACHE_DIR = "~/.cache/public-text-guard"
40
+ STATE_DIR_ENV = "PUBLIC_TEXT_GUARD_STATE_DIR"
41
+ STATE_DIR = "~/.local/state/public-text-guard"
42
+ CONFIG_ENV = "PUBCHECK_CONFIG"
43
+ CONFIG_FILE = "~/.config/pubcheck/config.toml"
44
+
45
+ #: The settings and their defaults. Everything that names the operator's own repos or
46
+ #: folders is unset by default and lives in their config file, never in this code:
47
+ #:
48
+ #: - ``hold_repo``: the private repo where a held post becomes a desk item (unset: no item
49
+ #: is filed; it must be private, or nothing is copied there);
50
+ #: - ``hold_label``: the label the desk reads;
51
+ #: - ``private_owner``: the account whose ``<owner>/_<name>`` repos are private companions
52
+ #: (a reference to one is private, and a flag points at the target's companion);
53
+ #: - ``private_issues``: the private repo for context that has no companion;
54
+ #: - ``private_patterns``: more regexes for private references (working folders, the
55
+ #: layout of the operator's machines), on top of this machine's home folder.
56
+ DFLT_SETTINGS = {
57
+ "hold_repo": None,
58
+ "hold_label": "escalate",
59
+ "budget_seconds": BUDGET_SECONDS,
60
+ "private_owner": None,
61
+ "private_issues": None,
62
+ "private_patterns": (),
63
+ }
64
+ #: The environment variable that overrides each setting (``private_patterns``: config only).
65
+ SETTINGS_ENV = {
66
+ "hold_repo": "PUBCHECK_HOLD_REPO",
67
+ "hold_label": "PUBCHECK_HOLD_LABEL",
68
+ "budget_seconds": "PUBCHECK_BUDGET_SECONDS",
69
+ "private_owner": "PUBCHECK_PRIVATE_OWNER",
70
+ "private_issues": "PUBCHECK_PRIVATE_ISSUES",
71
+ }
72
+
73
+
74
+ class Budget:
75
+ """One deadline shared by every lookup of a check."""
76
+
77
+ def __init__(self, seconds: float | None = BUDGET_SECONDS):
78
+ self.deadline = None if seconds is None else time.monotonic() + seconds
79
+
80
+ def left(self, cap: float = LOOKUP_TIMEOUT) -> float:
81
+ """Seconds a lookup may take: ``cap``, or what is left of the budget when less."""
82
+ if self.deadline is None:
83
+ return cap
84
+ return min(cap, self.deadline - time.monotonic())
85
+
86
+ def run(self, argv, *, cap: float = LOOKUP_TIMEOUT, stdin: str | None = None):
87
+ """``subprocess.run`` within the budget; ``None`` when out of time or on failure."""
88
+ left = self.left(cap)
89
+ if left <= 0.05:
90
+ return None
91
+ try:
92
+ return subprocess.run(
93
+ argv, capture_output=True, text=True, timeout=left, input=stdin
94
+ )
95
+ except (OSError, subprocess.SubprocessError):
96
+ return None
97
+
98
+
99
+ def write_private(path, text: str, *, append: bool = False) -> None:
100
+ """Write ``text`` to ``path`` with mode 0600, in a 0700 folder (atomically unless appending)."""
101
+ path = Path(path)
102
+ try:
103
+ path.parent.mkdir(parents=True, exist_ok=True)
104
+ os.chmod(path.parent, 0o700)
105
+ if append:
106
+ fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
107
+ with os.fdopen(fd, "a") as f:
108
+ f.write(text)
109
+ return
110
+ tmp = path.with_name(path.name + ".tmp")
111
+ fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
112
+ with os.fdopen(fd, "w") as f:
113
+ f.write(text)
114
+ tmp.replace(path)
115
+ except OSError:
116
+ pass
117
+
118
+
119
+ def cache_dir() -> Path:
120
+ """Where the vocabulary and the companion answers are cached."""
121
+ return Path(os.environ.get(CACHE_DIR_ENV) or CACHE_DIR).expanduser()
122
+
123
+
124
+ def settings(overrides: Mapping | None = None) -> dict:
125
+ """:data:`DFLT_SETTINGS`, then the config file, then the environment, then ``overrides``.
126
+
127
+ >>> settings({"hold_repo": "me/_desk"})["hold_repo"]
128
+ 'me/_desk'
129
+ """
130
+ out = dict(DFLT_SETTINGS)
131
+ path = Path(os.environ.get(CONFIG_ENV) or CONFIG_FILE).expanduser()
132
+ if path.is_file():
133
+ try:
134
+ data = tomllib.loads(path.read_text())
135
+ except (OSError, ValueError):
136
+ data = {}
137
+ out.update(data) # unknown keys are kept: a detector may read its own settings
138
+ for key, var in SETTINGS_ENV.items():
139
+ if os.environ.get(var):
140
+ out[key] = os.environ[var]
141
+ out.update({k: v for k, v in (overrides or {}).items() if v is not None})
142
+ out["budget_seconds"] = float(out["budget_seconds"])
143
+ out["private_patterns"] = tuple(out["private_patterns"] or ())
144
+ return out
145
+
146
+
147
+ def text_hash(*texts: str) -> str:
148
+ """A short hash of the texts: pairs log events and desk items without copying the text."""
149
+ digest = hashlib.sha256("\x00".join(t or "" for t in texts).encode()).hexdigest()
150
+ return digest[:16]
151
+
152
+
153
+ def log_event(**fields) -> None:
154
+ """Append one event to the private log; never raises."""
155
+ d = Path(os.environ.get(STATE_DIR_ENV) or STATE_DIR).expanduser()
156
+ record = {"v": 2, "time": time.strftime("%Y-%m-%dT%H:%M:%S%z"), **fields}
157
+ write_private(d / "events.jsonl", json.dumps(record) + "\n", append=True)