outlooks 0.2.0__tar.gz

outlooks-0.2.0/.gitignore

@@ -0,0 +1,22 @@
+.archive/
+.claude/
+.hypothesis/
+.pytest_cache/
+.ruff_cache/
+.venv/
+.vscode/
+.worktrees/
+
+__pycache__/
+build/
+dist/
+*.egg-info/
+
+.DS_Store
+
+.coverage
+.coverage.*
+
+.env
+.env.*
+!.env.example

outlooks-0.2.0/CHANGELOG.md

@@ -0,0 +1,147 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+A repo that builds on this package depends on more than its commands. A
+change to any of the following is listed under *Changed* or *Removed*, with
+what a consuming repo has to do about it:
+
+- a public Python name or one of its parameters (the README's "Python API");
+- a settings key or its default. A default counts because a repo that leaves
+  a key unset still has the default's path in its hook script and its ignore
+  file;
+- the archive's file format;
+- a command's name or exit code;
+- a line another tool is told to read: the `coverage` footer (`ledger
+  high-water mark`, `coverage ends`, `next sweep from`), and `COVERED`,
+  `INCOMPLETE`, and `DIFFERS` from `import`;
+- a skill step's name;
+- a key of a lookup's timeline file.
+
+## [Unreleased]
+
+## [0.2.0] - 2026-09-29
+
+### Added
+
+- A declared Python API: `store`, `classify`, `detail`, and `config` each
+  name what a consuming repo may import in `__all__`, listed in the README's
+  "Python API" section with a reading example and an example of refining a
+  `system` role in the repo's own wrapper. Every other module says in its
+  docstring that it is internal. A contract test pins the names, and each
+  function's parameter names, which of them have a default, and how each
+  may be passed.
+- `outlooks coverage --ledger <path>` reads a ledger kept somewhere other
+  than `ledger.csv` in `archive_dir`. A path that is not a file is an error
+  (exit 1), never an empty ledger.
+- `outlooks lookup-reset <name>` moves a lookup's page and timeline files
+  to `earlier/{timestamp}/` under `scratch_dir` and prints what it moved, so
+  a repeat lookup of a name never merges the last one's pages. It deletes
+  nothing, and the lookup skill runs it before launching searchers.
+- `outlooks doc lookup/timeline` lists every key of a lookup's timeline
+  file, which of them `check` reads, and which are required.
+- `outlooks doctor` checks in one read-only pass that a repo is wired
+  correctly, one line per check, and exits 1 if any fails: the settings
+  (the table is there, every key is a setting, and each parses), the
+  profile (the file exists when `profile` is set), the archive
+  (`coverage.csv` and every hits file parse), the hook script, the hook's
+  settings entry, and the skill stub. It makes no connector call, so a
+  consuming repo's CI can run it.
+- `outlooks senders [--since YYYY-MM-DD]` counts the archived inbound hits
+  by sender address, most frequent first, and marks each `own`, `system`, or
+  `unlisted`, so a notifier missing from `system_senders` is visible.
+  Read-only. The profile template's *Who we are* points at it.
+- Every step of the three modes has a fixed name, given where the step
+  starts (the sweep's are `setup`, `sweep`, `classify`, `match`, `worklist`,
+  `file`, `ledger`, and `report`). A repo's own skill or profile cites a step
+  by name, which a renumbering does not change; `outlooks doc
+  profile-template` says so. A test pins the names and their order per mode.
+- The README gives one install recipe for a repo that only runs the
+  commands and one for a repo that imports the package, an upgrade recipe
+  that ends in `outlooks doctor`, a CI example, how to run any command
+  against a copy of the archive, and the fixture a consuming repo's tests
+  pin the settings with.
+
+### Changed
+
+- `outlooks coverage` ends with one more line, `next sweep from`, giving the
+  instant the next sweep passes as `afterDateTime`, in UTC: the earlier of
+  the ledger's high-water mark less five minutes and the end of recorded
+  coverage. The sweep reads it, where it used to compute it. With an empty
+  ledger the line is the end of recorded coverage, and the sweep still asks
+  the operator where to start, because the archived mail before that instant
+  has never been classified. A tool that reads the footer should find each
+  line by its label, not its position.
+- `outlooks import` names the fields that differ on a `DIFFERS` line (`DIFFERS
+  from the stored copy in body.content, attachments[].uri: <path>`) and no
+  longer says `(--replace rewrites)`. A tool that matches the line should
+  match on `DIFFERS from the stored copy` and take the path after the last
+  `: `. The line names no field, `DIFFERS from the stored copy: <path>`,
+  when the stored copy is not JSON. The README says when `--replace` is the
+  fix.
+- `outlooks check` prints why a row is `BAD` on a line of its own under the
+  row: `missing key date_local` (or `internet_message_id`), `not archived`,
+  or the two dates that disagree. A timeline file with no
+  `internet_message_id` used to stop the command with a traceback, and one
+  with no `date_local` read as a date mismatch. The exit code is unchanged.
+
+### Fixed
+
+- `outlooks split <name>` no longer merges the page files of another lookup
+  whose name starts with `<name>-` (`smith` and `smith-jones`). A page file
+  is the name, one of the searchers' kinds (`sender`, `title`, `sent`) or
+  none, and `page-{n}.json`.
+
+## [0.1.0] - 2026-09-27
+
+### Added
+
+- The mailbox archive: the two-tier, write-once store (`store`), the capture
+  import (`capture`), window coverage (`coverage`), window sizing and the
+  item-id proof (`sizing`), the backfill planner (`window_plan`), message
+  classification (`classify`), the message detail view (`detail`), and the
+  `.docx` transcription (`render`).
+- `[tool.outlooks]` configuration with `OUTLOOKS_*` overrides, printed by
+  `outlooks config`: `mailbox`, `own_addresses`, `system_senders`,
+  `decision_tag`, `archive_dir`, `captured_dir`, `scratch_dir`, `timezone`,
+  `render_label` (the label `render` gives a file when `--label` is not
+  passed, default `Message`), and `profile`.
+- The signed-in account's own mailbox: with `mailbox` unset the archive files
+  under the first of `own_addresses`, and `import` takes the captures that
+  name no mailbox or name any own address. Its pulls report no total, so a
+  window is covered once its last page is captured.
+- The skill helpers as commands: `split`, `check`, `worklist`, `totals`,
+  `audit`, `windows`, and `hash`; `hook` writes and checks the capture hook,
+  whose script writes to the repo's `captured_dir`.
+- The `outlooks` skill (lookup, sweep, window) and its reference documents,
+  installed as a version-stamped stub through pkgskills. The sweep takes the
+  ledger's classification column name and outcome words from the profile
+  when it gives them, and skipping replies is a default the profile can
+  override.
+- Message roles from `classify`: `arrival`, `followup`, `ours`, `decision`
+  (our mail with the `decision_tag` in its subject, reported with the label
+  after the tag), and `system` (mail from one of `system_senders`).
+- Mass sends: a hand-owned `mass-sends.csv` beside the archive (`sender`,
+  `subject`, `after`, `before`, `exemplar`) lists the bulk sends whose copies
+  differ only in the recipient. `worklist` reads the exemplar and skips the
+  other copies; `coverage` counts them on their own line rather than as
+  covered mail with no full read.
+- `worklist` refuses, writing nothing, while the newest capture was written
+  under 90 seconds ago, so a reader still running never has its batch files
+  replaced.
+- `outlooks hook` reads a script written by a pre-release build as `stale`,
+  so `--apply` rewrites it; for a script with a local change it says that
+  `--apply --force` overwrites it.
+
+### Security
+
+- The capture hook and `outlooks import` follow the saved-file path in an
+  oversized-result note only into Claude Code's projects directory
+  (`~/.claude/projects/`, or under `CLAUDE_CONFIG_DIR`), comparing folders as
+  the filesystem resolves them and refusing a file that is itself a link, so
+  neither a `..` nor a link leads out of it. A test or tool that feeds the
+  hook a spill note must put the saved file, as a regular file, under that
+  directory; anywhere else, nothing is copied.

outlooks-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ronald E. Robertson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

outlooks-0.2.0/PKG-INFO

@@ -0,0 +1,327 @@
+Metadata-Version: 2.5
+Name: outlooks
+Version: 0.2.0
+Summary: Archive and read an Outlook mailbox through the Microsoft 365 connector, with the Claude Code skill that drives it.
+Project-URL: repository, https://github.com/gitronald/outlooks
+Author-email: gitronald <gitronald@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: pkgskills<0.6.0,>=0.5.1
+Requires-Dist: typer>=0.15.0
+Description-Content-Type: text/markdown
+
+# outlooks
+
+Archive and read an Outlook mailbox through the claude.ai Microsoft 365
+connector, and ship the Claude Code skill that drives it.
+
+The connector is only reachable from an interactive Claude Code session, so
+this package never talks to Microsoft itself. A PostToolUse hook writes every
+`outlook_email_search` and `read_resource` result verbatim to a captures
+directory; `outlooks import` files those captures into a committed, write-once
+archive, and records every date window whose pages were all captured as
+covered. The skill (`/outlooks`) tells an agent how to search, page, and read
+the mailbox so that the archive fills itself.
+
+## Install
+
+Python 3.11 or later. `render` needs [pandoc](https://pandoc.org) on the PATH.
+
+There are two recipes, one for each way a repo uses the package. Both pin a
+release.
+
+### Operator only
+
+The repo runs the commands, the skill, and the capture hook from an
+interactive session, and none of its own code imports `outlooks`. Put the
+package in a dependency group of its own, so it is installed for the
+operator and the repo's package cannot come to depend on it by accident:
+
+```toml
+[dependency-groups]
+mailbox = ["outlooks==X.Y.Z"]
+
+[tool.uv]
+default-groups = ["dev", "mailbox"]
+```
+
+### Importing
+
+The repo's own code or tests `import outlooks` (see [Python API](#python-api)).
+It is a plain dependency:
+
+```bash
+uv add "outlooks==X.Y.Z"
+```
+
+### Either way
+
+```bash
+uv sync
+uv run outlooks install       # the /outlooks skill stub, under .claude/skills/
+uv run outlooks hook --apply  # the capture hook script and its settings entry
+uv run outlooks doctor        # every check reads ok
+```
+
+Where the package index cannot be used, the same release installs from its
+tag. Keep the dependency as above and add a source:
+
+```toml
+[tool.uv.sources]
+outlooks = { git = "https://github.com/gitronald/outlooks", tag = "vX.Y.Z" }
+```
+
+A git source cannot be resolved on a network that allows only the package
+index, and it pins one tag, not a version range, so the index is the first
+choice.
+
+### In CI
+
+`outlooks doctor` makes no connector call, so CI can run it. It checks what
+the repo commits: the `[tool.outlooks]` table, the profile, the archive, and,
+under `.claude/`, the hook script, `settings.json`, and the skill stub.
+
+```yaml
+- run: uv sync --frozen
+- run: uv run outlooks doctor
+```
+
+## Upgrade
+
+```bash
+# 1. change the version (or the tag) in pyproject.toml, then
+uv lock --upgrade-package outlooks
+uv sync
+uv run outlooks hook --apply   # rewrites a hook script an earlier release wrote
+uv run outlooks install        # rewrites the skill stub for the new version
+uv run outlooks doctor
+```
+
+Read the changelog's *Changed* and *Removed* entries for every release
+between the two versions first: they say what a consuming repo has to do.
+
+The lock file is the pin that holds. For a release from the index it records
+the version and the hashes of its files, and for a git source the commit the
+tag resolved to, so `uv sync --frozen` installs the same code whatever
+happens upstream.
+
+## Configure
+
+Everything repo-specific comes from `[tool.outlooks]` in the nearest
+`pyproject.toml` holding the table, each key overridable by an
+`OUTLOOKS_{KEY}` environment variable. Paths are relative to that file.
+
+```toml
+[tool.outlooks]
+mailbox = "team@example.org"            # unset: the signed-in account's own mailbox
+own_addresses = ["team@example.org"]    # default: [mailbox]; required when mailbox is unset
+system_senders = ["notices@system.example.org"]
+decision_tag = "[Decision]"
+archive_dir = "data/outlook"
+captured_dir = "temp/outlook/captured"
+scratch_dir = "temp/outlook"
+timezone = "America/Los_Angeles"
+render_label = "Message"                # render's --label when none is passed
+profile = "docs/outlook-profile.md"
+```
+
+For the signed-in account's own mailbox, leave `mailbox` unset and list the
+account's addresses in `own_addresses`: the archive files under the first of
+them. Its searches report no totals, so a window counts as covered once its
+last page is captured, and the window planner does not apply.
+
+`uv run outlooks config` prints the effective values and where each came from.
+The `profile` is repo-owned prose the skill reads for what this package cannot
+know: where a name resolves, how the sweep classifies, what filing a candidate
+means, and which of the repo's own records a message can contradict. `uv run
+outlooks doc profile-template` prints the headings it should answer.
+
+## Trying it without touching the archive
+
+Every path is a setting, and every setting has an `OUTLOOKS_*` override, so
+any command runs against a copy. To see what `import --replace` would
+rewrite before it rewrites anything:
+
+```bash
+cp -r data/outlook temp/outlook-trial
+OUTLOOKS_ARCHIVE_DIR=temp/outlook-trial \
+OUTLOOKS_SCRATCH_DIR=temp/outlook-trial-scratch \
+  uv run outlooks import --replace
+git diff --no-index data/outlook temp/outlook-trial
+```
+
+The captures are only read, so `captured_dir` can stay as it is.
+`outlooks config` run with the same variables shows each path and that it
+came from the environment.
+
+## The archive
+
+| Path | Holds |
+|---|---|
+| `hits/{mailbox}/{YYYY-MM}.jsonl` | every search hit ever listed, deduped by `internetMessageId` |
+| `messages/{id-hash}.json` | full `read_resource` payloads, bodies raw |
+| `messages/{id-hash}.{n}.txt` | attachment `n`'s extracted text |
+| `coverage.csv` | one row per window pull that ran to completion |
+| `mass-sends.csv` | optional, hand-owned: bulk sends whose copies are read once |
+
+`{id-hash}` is the first 16 hex digits of the SHA-256 of the
+`internetMessageId` (`outlooks hash <id>`). Both tiers are write-once: a second
+import of an unchanged message is a no-op, and one that differs is listed, not
+rewritten:
+
+```
+  DIFFERS from the stored copy in body.content, attachments[].uri: temp/outlook/captured/20260105T101500-4242.json
+```
+
+The line names the fields that differ, so the two copies need no diffing by
+hand. It names none when the stored copy is not JSON. Which copy is right
+decides what to do:
+
+- **The stored copy was not written from a capture** (it was saved by hand
+  with `outlooks save`, or typed out): the capture is the connector's own
+  output, and `outlooks import --replace` rewrites the stored copy from it.
+- **The capture is the older of the two** (the message changed after the
+  capture was written, and the stored copy came from a later read): the
+  stored copy is right. Leave it, and do not pass `--replace`.
+
+`outlooks import <paths> --replace` limits the rewrite to the captures named,
+so one repair never rewrites anything else that differs.
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `outlooks import [paths] [--replace]` | file the hook's captures; record complete windows |
+| `outlooks coverage [--since] [--ledger]` | covered windows, gaps, unread counts, ledger lag, and the next sweep's start |
+| `outlooks senders [--since]` | inbound hits counted by sender, each marked `own`, `system`, or `unlisted` |
+| `outlooks split <name> --match ...` | a lookup's hits: archived (timeline written) vs to-read |
+| `outlooks check <name>` | a lookup's timeline files against the archive |
+| `outlooks lookup-reset <name>` | move a lookup's page and timeline files aside before a repeat lookup |
+| `outlooks worklist --after --before --out` | reader worklists for a full read of a range |
+| `outlooks totals [prefix ...]` / `--check AFTER BEFORE` | window sizes; the item-id proof |
+| `outlooks windows init/fill/split/batches/remaining` | the backfill planner |
+| `outlooks audit <prefix> [--sweep]` | attachment-text audit for a period |
+| `outlooks render <message.json>` | a message as `{Surname} - {render_label}.docx` (pandoc, sandboxed) |
+| `outlooks save <payload>` | archive a hand-saved payload (sessions use `import`) |
+| `outlooks hash <id>` | a message's archive file stem |
+| `outlooks hook [--apply]` | check or wire the capture hook |
+| `outlooks config` | the effective settings |
+| `outlooks doctor` | settings, profile, archive, hook, and skill stub in one read-only pass; exit 1 if any check fails |
+| `outlooks skill`, `outlooks doc`, `outlooks install`, `outlooks permissions` | the skill, its documents, the stub, and its permission profile ([pkgskills](https://github.com/gitronald/pkgskills)) |
+
+## Python API
+
+A repo that imports this package may import the names below, and nothing
+else. Every other module is internal, and the commands are its interface. A
+change to one of these names, or to a parameter of one, is listed in the
+changelog under *Changed* or *Removed*.
+
+| Module | Public names |
+|---|---|
+| `outlooks.store` | `archive_root`, `id_hash`, `stable`, `load_hits`, `load_messages`, `newest_hit`, `StoreError` |
+| `outlooks.classify` | `Mail`, `Facts`, `view`, `classify`, `is_reply`, `thread_subject` |
+| `outlooks.detail` | `detail`, `details_by_id`, `body_text` |
+| `outlooks.config` | `Settings`, `load`, `settings`, `KEYS`, `DEFAULTS`, `ConfigError`, `mailbox`, `archive_dir`, `captured_dir`, `scratch_dir`, `zone`, `zone_label` |
+
+The API reads the archive and never writes it: a repo fills the archive
+through `outlooks import`.
+
+Reading the archive:
+
+```python
+from outlooks import classify, detail, store
+
+hits = store.load_hits()  # every message ever listed, by internetMessageId
+messages = store.load_messages()  # the ones read in full
+
+for mid, hit in hits.items():
+    mail = classify.view(messages.get(mid, hit))
+    role = classify.classify(mail).role
+    print(mail.day, role, mail.sender, mail.subject)
+
+for mid, message in messages.items():
+    fields = detail.detail(message)  # from, to, cc, bcc, attachments, body
+```
+
+`classify` reports the role a message plays (`arrival`, `followup`, `ours`,
+`decision`, `system`) and stops there. What a system sender's notification
+says is the repo's own business, and the place for it is a thin wrapper in
+the repo. For a ticketing system whose notices read "Ticket #12 was opened
+by ...":
+
+```python
+import re
+
+from outlooks import classify as cl
+
+OPENED = re.compile(r"Ticket #(\d+) was opened by (.+?)\.")
+
+
+def facts(payload):
+    mail = cl.view(payload)
+    base = cl.classify(mail)
+    if base.role != "system":
+        return base.role, None
+    found = OPENED.search(mail.text)
+    return ("system-opened", int(found[1])) if found else ("system-other", None)
+```
+
+`Mail` carries what such a wrapper reads: `sender`, `recipients`, `subject`,
+and `text` (the body as plain text for a message read in full, the summary
+for a search hit).
+
+## Testing against it
+
+A consuming repo's tests pin every setting through `OUTLOOKS_*` in a
+fixture, so they never read the repo's own `[tool.outlooks]` table, its
+archive, or the zone of the machine they run on:
+
+```python
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def outlooks_settings(monkeypatch, tmp_path):
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("OUTLOOKS_MAILBOX", "desk@example.org")
+    monkeypatch.setenv("OUTLOOKS_OWN_ADDRESSES", "desk@example.org")
+    monkeypatch.setenv("OUTLOOKS_SYSTEM_SENDERS", "notices@system.example.org")
+    monkeypatch.setenv("OUTLOOKS_DECISION_TAG", "[Decision]")
+    monkeypatch.setenv("OUTLOOKS_TIMEZONE", "America/Los_Angeles")
+    monkeypatch.setenv("OUTLOOKS_ARCHIVE_DIR", str(tmp_path / "archive"))
+    monkeypatch.setenv("OUTLOOKS_CAPTURED_DIR", str(tmp_path / "captured"))
+    monkeypatch.setenv("OUTLOOKS_SCRATCH_DIR", str(tmp_path / "scratch"))
+    monkeypatch.delenv("OUTLOOKS_PROFILE", raising=False)
+    monkeypatch.delenv("OUTLOOKS_RENDER_LABEL", raising=False)
+```
+
+The settings are resolved again whenever the working directory or an
+`OUTLOOKS_*` variable changes, so a test that sets one more variable gets
+it. A test that needs an archive writes its own messages under `tmp_path`
+in the connector's shape, with invented senders.
+
+## Development
+
+```bash
+uv sync --all-groups
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run pyrefly check
+```
+
+The tests use synthetic fixtures only (`example.org` addresses and an invented
+cast), and every test runs in its own temporary directory with its settings
+pinned through `OUTLOOKS_*`, so the suite never reads a real archive.
+
+### Releases
+
+A published tag never moves. A fix ships as the next version, under its own
+changelog heading, because a consuming repo's lock file names the commit a
+tag resolved to, and a tag that moved would leave two repos on the same
+version running different code.
+
+The changelog's preamble lists what counts as a change a consuming repo has
+to hear about. Each such change is entered under *Changed* or *Removed*,
+with what to do.