earnings-watch 0.1.0__tar.gz

earnings_watch-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,15 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: make bootstrap
+      - run: make check

earnings_watch-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,235 @@
+name: Release
+on:
+  push:
+    tags: ['v*.*.*']
+  workflow_dispatch: {}
+permissions:
+  contents: read
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+jobs:
+  released:
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    outputs:
+      exists: ${{ steps.check.outputs.exists }}
+    steps:
+      - id: check
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if gh release view "$GITHUB_REF_NAME" -R "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            echo exists=true >> "$GITHUB_OUTPUT"
+          else
+            echo exists=false >> "$GITHUB_OUTPUT"
+          fi
+  test:
+    needs: released
+    if: needs.released.outputs.exists != 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: make bootstrap
+      - run: make check
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/*
+  images:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    strategy:
+      matrix:
+        target: [serve, worker]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+        id: builder
+        with:
+          use: false
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - id: metadata
+        shell: bash
+        run: |
+          name=earnings-watch
+          if [ '${{ matrix.target }}' = worker ]; then name=earnings-watch-worker; fi
+          echo name="$name" >> "$GITHUB_OUTPUT"
+          echo version="${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+      - id: build
+        uses: docker/build-push-action@v6
+        with:
+          builder: ${{ steps.builder.outputs.name }}
+          context: .
+          target: ${{ matrix.target }}
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ghcr.io/${{ github.repository_owner }}/${{ steps.metadata.outputs.name }}:candidate-${{ github.sha }}
+          labels: |
+            org.opencontainers.image.source=https://github.com/${{ github.repository }}
+            org.opencontainers.image.revision=${{ github.sha }}
+            org.opencontainers.image.version=${{ steps.metadata.outputs.version }}
+      - env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+        run: |
+          mkdir -p digests
+          printf '%s\n' "$DIGEST" > 'digests/${{ steps.metadata.outputs.name }}'
+      - uses: actions/upload-artifact@v4
+        with:
+          name: digest-${{ matrix.target }}
+          path: digests/*
+  smoke:
+    needs: images
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        image: [earnings-watch, earnings-watch-worker]
+        arch: [amd64, arm64]
+    steps:
+      - uses: docker/setup-qemu-action@v3
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: digest-*
+          path: digests
+          merge-multiple: true
+      - env:
+          IMAGE: ghcr.io/${{ github.repository_owner }}/${{ matrix.image }}
+          ARCH: ${{ matrix.arch }}
+        run: |
+          digest="$(cat 'digests/${{ matrix.image }}')"
+          docker run --rm --platform "linux/$ARCH" --read-only --cap-drop ALL --security-opt no-new-privileges --tmpfs /data:uid=1000,gid=1000,mode=0700 --tmpfs /tmp --entrypoint sh "$IMAGE@$digest" -c 'earnings-watch init && earnings-watch doctor && earnings-watch upcoming --format json'
+          if [ '${{ matrix.image }}' = earnings-watch-worker ]; then
+            docker run --rm --platform "linux/$ARCH" --entrypoint claude "$IMAGE@$digest" --version
+            docker run --rm --platform "linux/$ARCH" --entrypoint codex "$IMAGE@$digest" --version
+          fi
+  promote:
+    needs: smoke
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: digest-*
+          path: digests
+          merge-multiple: true
+      - env:
+          OWNER: ${{ github.repository_owner }}
+        run: |
+          set -eu
+          version="${GITHUB_REF_NAME#v}"
+          for name in earnings-watch earnings-watch-worker; do
+            image="ghcr.io/$OWNER/$name"
+            if docker buildx imagetools inspect "$image:$version" >/dev/null 2>&1; then
+              echo "Release version already exists; use a new version."
+              exit 1
+            fi
+          done
+          for name in earnings-watch earnings-watch-worker; do
+            image="ghcr.io/$OWNER/$name"
+            digest="$(cat "digests/$name")"
+            docker buildx imagetools create --prefer-index=false --tag "$image:$version" --tag "$image:latest" "$image@$digest"
+          done
+  github-release:
+    needs: [test, promote]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist
+      - env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          cd dist
+          sha256sum * > SHA256SUMS
+          gh release create "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" --verify-tag --title "$GITHUB_REF_NAME" --generate-notes ./*
+  pypi:
+    needs: [released, github-release]
+    if: >-
+      always() && github.ref_type == 'tag' && vars.PYPI_PUBLISH == 'true' &&
+      (needs.github-release.result == 'success' || needs.released.outputs.exists == 'true')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -eu
+          gh release download "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" --dir dist --pattern '*.whl' --pattern '*.tar.gz' --pattern SHA256SUMS
+          (cd dist && sha256sum --check SHA256SUMS)
+          uv tool run --from twine twine check --strict dist/*.whl dist/*.tar.gz
+          uv venv /tmp/earnings-wheel-check
+          uv pip install --python /tmp/earnings-wheel-check/bin/python dist/*.whl
+          EARNINGS_WATCH_DATA_DIR=/tmp/earnings-release-state /tmp/earnings-wheel-check/bin/earnings-watch init
+          EARNINGS_WATCH_DATA_DIR=/tmp/earnings-release-state /tmp/earnings-wheel-check/bin/earnings-watch doctor
+          rm dist/SHA256SUMS
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086
+        with:
+          attestations: true
+          skip-existing: true
+  registry:
+    needs: [released, github-release, pypi]
+    if: >-
+      always() && github.ref_type == 'tag' && vars.MCP_REGISTRY_PUBLISH == 'true' &&
+      (needs.github-release.result == 'success' || needs.released.outputs.exists == 'true')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    env:
+      MCP_PUBLISHER_VERSION: v1.8.1
+    steps:
+      - uses: actions/checkout@v4
+      - uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6
+      - name: Verify the publisher and the published package
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -eu
+          version="${GITHUB_REF_NAME#v}"
+          curl --fail --silent --show-error "https://pypi.org/pypi/earnings-watch/$version/json" -o /tmp/package.json
+          gh release download "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" --pattern SHA256SUMS --dir /tmp/earnings-registry-assets
+          python3 - <<'PY'
+          import json
+          from pathlib import Path
+          published = json.loads(Path('/tmp/package.json').read_text())
+          expected = dict(line.split()[::-1] for line in Path('/tmp/earnings-registry-assets/SHA256SUMS').read_text().splitlines())
+          actual = {item['filename']: item['digests']['sha256'] for item in published['urls']}
+          if not expected or expected != actual:
+              raise SystemExit('PyPI files differ from the accepted GitHub release')
+          PY
+          archive=mcp-publisher_linux_amd64.tar.gz
+          base_url="https://github.com/modelcontextprotocol/registry/releases/download/$MCP_PUBLISHER_VERSION"
+          curl --fail --location --silent --show-error -o "$archive" "$base_url/$archive"
+          curl --fail --location --silent --show-error -o "$archive.sigstore.json" "$base_url/$archive.sigstore.json"
+          cosign verify-blob --bundle "$archive.sigstore.json" --certificate-identity "https://github.com/modelcontextprotocol/registry/.github/workflows/release.yml@refs/tags/$MCP_PUBLISHER_VERSION" --certificate-oidc-issuer https://token.actions.githubusercontent.com "$archive"
+          tar xzf "$archive" mcp-publisher
+          jq --arg version "$version" '.version = $version | .packages[].version = $version' server.json > server-release.json
+          mv server-release.json server.json
+      - run: |
+          ./mcp-publisher login github-oidc
+          ./mcp-publisher publish

earnings_watch-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+*.egg-info/
+*.db*
+.artifacts/

earnings_watch-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0
+
+Initial standalone CLI, Python API and MCP server. Shared SQLite facts with personal follows, delegated calendar plans and durable delivery state; deterministic date/timing verification; official release polling, document links and opt-in downloads; standalone and gateway HTTP authentication; separate serving and maintenance images.
+
+Candidate audit fixes preserve revisions and download receipts across catalogue
+retirement, cover the full release-polling window, keep accepted documents after
+partial provider failures, align date boundaries to UTC, treat disabled models
+as intentional, and harden interrupted HTTP requests and download integrity.
+Existing schema-1 candidates upgrade explicitly through `init`; see operations.
+
+- Preserve legacy polling, document verification and reviewed overrides during
+  migration; block external effects until explicit reconciliation, and export
+  current-state compatibility projections with retained rollback evidence.
+- Bind concurrent image builds to their own builders so one completed job cannot
+  stop another job's qualification or release build.

earnings_watch-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,9 @@
+# Contributing
+
+Report bugs with synthetic inputs and redacted diagnostics. Do not attach account tokens, personal follows, calendar records or captured private pages.
+
+## How changes land
+
+This repository is a release mirror. Maintained source is reviewed separately and exported as complete releases. Pull requests are reviewed and reimplemented in that source, then credited in release notes; they are not merged directly into the mirror because the next export would replace them.
+
+Run `make bootstrap` and `make check`. Keep network, models and account effects behind fake boundaries in offline tests. Add a regression test when changing date, period, timing, persistence or authentication behavior. Public fixtures must be fictional.

earnings_watch-0.1.0/Dockerfile

@@ -0,0 +1,27 @@
+FROM node:24-bookworm-slim AS clis
+RUN npm install --prefix /opt/clis @anthropic-ai/claude-code@2.1.312 @openai/codex@0.164.0
+FROM ghcr.io/astral-sh/uv:0.13.5 AS uv
+FROM python:3.12-slim-bookworm AS base
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 HOME=/home/earnings EARNINGS_WATCH_DATA_DIR=/data PATH=/app/.venv/bin:$PATH
+RUN useradd --uid 1000 --create-home earnings && mkdir /data && chown earnings /data
+WORKDIR /app
+FROM base AS dependencies
+COPY --from=uv /uv /usr/local/bin/uv
+COPY pyproject.toml uv.lock README.md LICENSE NOTICE ./
+COPY src ./src
+RUN uv sync --locked --no-dev --no-editable
+FROM base AS serve
+COPY --from=dependencies /app/.venv /app/.venv
+USER 1000:1000
+VOLUME /data
+HEALTHCHECK --interval=60s --timeout=10s CMD ["earnings-watch", "health", "--json"]
+ENTRYPOINT ["earnings-watch"]
+CMD ["serve", "--http", "--host", "0.0.0.0"]
+FROM serve AS worker
+USER root
+RUN apt-get update && apt-get install -y --no-install-recommends libstdc++6 ca-certificates && rm -rf /var/lib/apt/lists/*
+COPY --from=clis /usr/local/bin/node /usr/local/bin/node
+COPY --from=clis /opt/clis /opt/clis
+ENV PATH=/opt/clis/node_modules/.bin:$PATH
+USER 1000:1000
+CMD ["worker"]

earnings_watch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 benjamin-di
+
+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.

earnings_watch-0.1.0/Makefile

@@ -0,0 +1,20 @@
+.PHONY: bootstrap check test live conformance
+bootstrap:
+	uv sync --locked
+check:
+	uv lock --check
+	uv run --locked ruff check src tests scripts
+	uv run --locked ruff format --check src tests scripts
+	uv run --locked mypy src
+	uv run --locked python scripts/check-boundaries.py
+	uv run --locked pytest -m 'not live' -q
+	uv build --no-sources
+	git diff --check
+
+test:
+	uv run --locked pytest -q
+live:
+	uv run --locked pytest -m live private/ -q
+
+conformance:
+	uv run --locked python scripts/check-conformance.py

earnings_watch-0.1.0/NOTICE

@@ -0,0 +1,3 @@
+Earnings Watch
+
+The deterministic timing and verification engine was extracted from its original service.

earnings_watch-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.5
+Name: earnings-watch
+Version: 0.1.0
+Summary: Verified issuer earnings calendars and results documents, through CLI and MCP
+Project-URL: Homepage, https://github.com/benjamin-di/earnings-watch
+Author: benjamin-di
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.12
+Requires-Dist: fastmcp==4.1.3
+Requires-Dist: html2text>=2024.2
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pydantic<3,>=2.11
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: tzdata>=2024.1
+Description-Content-Type: text/markdown
+
+# Earnings Watch
+
+<!-- mcp-name: io.github.benjamin-di/earnings-watch -->
+
+Verified issuer earnings calendars and results documents through a CLI, Python API and MCP server. Models propose dates; deterministic checks require quoted evidence and consistent issuer, period and timing. A call time never silently becomes a publication time.
+
+Calendar updates are optional. Earnings Watch produces an operation plan; your MCP client uses its external Outlook app to apply it and acknowledges confirmed writes. No Microsoft credentials or calendar SDK are required by this package.
+
+Requires Python 3.12+. Install a release wheel with `uv tool install path/to/earnings_watch-0.1.0-py3-none-any.whl`, or develop from a source checkout:
+
+```sh
+make bootstrap
+uv run earnings-watch init
+uv run earnings-watch doctor
+uv run earnings-watch sources import examples/sources.yaml
+uv run earnings-watch watch EXAMPLE
+uv run earnings-watch upcoming --format json
+```
+
+The example uses reserved domains and fictional data; replace its source URLs and issuer metadata before fetching. There is no bundled issuer universe or market-data subscription.
+
+## Maintenance and models
+
+Serving reads SQLite and updates personal follows/ledgers; it never fetches issuer pages or calls a model. Run maintenance separately:
+
+```sh
+uv run earnings-watch sweep --dry-run
+uv run earnings-watch sweep
+uv run earnings-watch sweep --docs-only
+uv run earnings-watch worker
+```
+
+The default backend is `none`: it preserves existing dates and still polls official release providers. To extract new dates, install and sign into your own Claude Code or Codex CLI, then configure it in `earnings-watch.toml`:
+
+```toml
+[llm]
+backends = ["claude-code", "codex", "none"]
+max_calls_per_run = 20
+```
+
+Supported minimum versions are Claude Code 2.1.312 and Codex 0.164.0. Run `earnings-watch doctor --live` to check capabilities and an optional model canary. The package has no login flow. Model usage follows your CLI account's limits and terms. Missing credentials or capacity may try the next backend; a timed-out run is not repeated in the same tick.
+
+## MCP
+
+A local client configuration, after initialization:
+
+```json
+{"mcpServers":{"earnings":{"command":"earnings-watch","args":["serve","--stdio"]}}}
+```
+
+| Tool | Purpose |
+| --- | --- |
+| `earnings_upcoming` | Bounded upcoming dates with timing uncertainty |
+| `earnings_get_events` | Evidence, revisions and recent history |
+| `earnings_documents` | Official result-document links and verification status |
+| `earnings_changes` | Cursor-based public change feed |
+| `earnings_watchlist` | Your follows and registration states |
+| `earnings_watch` | Follow an issuer; queue registration or resolve ambiguity |
+| `earnings_unwatch` | Remove a manual follow |
+| `earnings_calendar_plan` | Plan optional external calendar operations |
+| `earnings_calendar_ack` | Record confirmed operations from a signed plan |
+| `earnings_status` | Catalogue and maintenance status |
+
+Prompts: `weekly_earnings_brief`, `results_brief`, `sync_to_my_outlook`. Resource: `earnings://upcoming.ics`. Exact times require verified clock and timezone evidence; otherwise calendar entries are all-day. Outlook operations never include attendees.
+
+HTTP standalone mode uses a separate bearer token per person at `/users/<id>/mcp`. Gateway mode accepts a configured backend bearer and trusted person header at `/mcp`. These modes are separate trust boundaries; see [permissions](docs/PERMISSIONS.md).
+
+## Docker Compose
+
+```sh
+cp earnings-watch.example.toml earnings-watch.toml
+docker compose build
+docker compose run --rm server init
+docker compose run --rm server users add example
+docker compose up -d
+```
+
+Save the returned token privately and use it only on that person's HTTP path. The server binds to loopback by default. Both images run as uid 1000; Compose drops capabilities, prevents privilege escalation and mounts the root filesystem read-only. The worker image includes pinned model CLIs; their auth volume is optional with `backends=["none"]`. Configure CLI sign-in outside the read-only worker before enabling model maintenance. Protect auth files and the data volume from other users.
+
+Use `--config PATH`, `--person ID`, and `--json` with the CLI. Settings come from TOML and `EARNINGS_WATCH_*` environment variables. See [operations](docs/OPERATIONS.md), [architecture](docs/ARCHITECTURE.md), [providers](docs/PROVIDERS.md) and [design decisions](docs/DESIGN.md).
+
+## Development
+
+`make check` verifies lock drift, lint, formatting, types, dependency boundaries, offline tests and wheel/source builds. Tests use synthetic issuers and fake network/model/account boundaries. Real-model and real-page checks are separate operator gates. Read [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
+
+See [implementation status](docs/IMPLEMENTATION.md) for completed capabilities,
+release gates and the production adapter work still required before cutover.

earnings_watch-0.1.0/README.md

@@ -0,0 +1,87 @@
+# Earnings Watch
+
+<!-- mcp-name: io.github.benjamin-di/earnings-watch -->
+
+Verified issuer earnings calendars and results documents through a CLI, Python API and MCP server. Models propose dates; deterministic checks require quoted evidence and consistent issuer, period and timing. A call time never silently becomes a publication time.
+
+Calendar updates are optional. Earnings Watch produces an operation plan; your MCP client uses its external Outlook app to apply it and acknowledges confirmed writes. No Microsoft credentials or calendar SDK are required by this package.
+
+Requires Python 3.12+. Install a release wheel with `uv tool install path/to/earnings_watch-0.1.0-py3-none-any.whl`, or develop from a source checkout:
+
+```sh
+make bootstrap
+uv run earnings-watch init
+uv run earnings-watch doctor
+uv run earnings-watch sources import examples/sources.yaml
+uv run earnings-watch watch EXAMPLE
+uv run earnings-watch upcoming --format json
+```
+
+The example uses reserved domains and fictional data; replace its source URLs and issuer metadata before fetching. There is no bundled issuer universe or market-data subscription.
+
+## Maintenance and models
+
+Serving reads SQLite and updates personal follows/ledgers; it never fetches issuer pages or calls a model. Run maintenance separately:
+
+```sh
+uv run earnings-watch sweep --dry-run
+uv run earnings-watch sweep
+uv run earnings-watch sweep --docs-only
+uv run earnings-watch worker
+```
+
+The default backend is `none`: it preserves existing dates and still polls official release providers. To extract new dates, install and sign into your own Claude Code or Codex CLI, then configure it in `earnings-watch.toml`:
+
+```toml
+[llm]
+backends = ["claude-code", "codex", "none"]
+max_calls_per_run = 20
+```
+
+Supported minimum versions are Claude Code 2.1.312 and Codex 0.164.0. Run `earnings-watch doctor --live` to check capabilities and an optional model canary. The package has no login flow. Model usage follows your CLI account's limits and terms. Missing credentials or capacity may try the next backend; a timed-out run is not repeated in the same tick.
+
+## MCP
+
+A local client configuration, after initialization:
+
+```json
+{"mcpServers":{"earnings":{"command":"earnings-watch","args":["serve","--stdio"]}}}
+```
+
+| Tool | Purpose |
+| --- | --- |
+| `earnings_upcoming` | Bounded upcoming dates with timing uncertainty |
+| `earnings_get_events` | Evidence, revisions and recent history |
+| `earnings_documents` | Official result-document links and verification status |
+| `earnings_changes` | Cursor-based public change feed |
+| `earnings_watchlist` | Your follows and registration states |
+| `earnings_watch` | Follow an issuer; queue registration or resolve ambiguity |
+| `earnings_unwatch` | Remove a manual follow |
+| `earnings_calendar_plan` | Plan optional external calendar operations |
+| `earnings_calendar_ack` | Record confirmed operations from a signed plan |
+| `earnings_status` | Catalogue and maintenance status |
+
+Prompts: `weekly_earnings_brief`, `results_brief`, `sync_to_my_outlook`. Resource: `earnings://upcoming.ics`. Exact times require verified clock and timezone evidence; otherwise calendar entries are all-day. Outlook operations never include attendees.
+
+HTTP standalone mode uses a separate bearer token per person at `/users/<id>/mcp`. Gateway mode accepts a configured backend bearer and trusted person header at `/mcp`. These modes are separate trust boundaries; see [permissions](docs/PERMISSIONS.md).
+
+## Docker Compose
+
+```sh
+cp earnings-watch.example.toml earnings-watch.toml
+docker compose build
+docker compose run --rm server init
+docker compose run --rm server users add example
+docker compose up -d
+```
+
+Save the returned token privately and use it only on that person's HTTP path. The server binds to loopback by default. Both images run as uid 1000; Compose drops capabilities, prevents privilege escalation and mounts the root filesystem read-only. The worker image includes pinned model CLIs; their auth volume is optional with `backends=["none"]`. Configure CLI sign-in outside the read-only worker before enabling model maintenance. Protect auth files and the data volume from other users.
+
+Use `--config PATH`, `--person ID`, and `--json` with the CLI. Settings come from TOML and `EARNINGS_WATCH_*` environment variables. See [operations](docs/OPERATIONS.md), [architecture](docs/ARCHITECTURE.md), [providers](docs/PROVIDERS.md) and [design decisions](docs/DESIGN.md).
+
+## Development
+
+`make check` verifies lock drift, lint, formatting, types, dependency boundaries, offline tests and wheel/source builds. Tests use synthetic issuers and fake network/model/account boundaries. Real-model and real-page checks are separate operator gates. Read [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
+
+See [implementation status](docs/IMPLEMENTATION.md) for completed capabilities,
+release gates and the production adapter work still required before cutover.

earnings_watch-0.1.0/SECURITY.md

@@ -0,0 +1,7 @@
+# Security
+
+Use GitHub's private vulnerability reporting for security issues. Never publish credentials, database files, calendar handles or raw private diagnostics in an issue.
+
+Keep the data/auth volumes private and use TLS for remote HTTP. Standalone per-person tokens and gateway backend credentials have different authority; see [permissions](docs/PERMISSIONS.md). Do not expose gateway mode directly to untrusted callers.
+
+Security-relevant fixes receive a new release. Treat model output, captured pages, document links and mirror contributions as untrusted inputs. Financial dates and document verification are evidence checks, not investment advice or financial-content certification.

earnings_watch-0.1.0/compose.yaml

@@ -0,0 +1,27 @@
+services:
+  server:
+    image: ghcr.io/benjamin-di/earnings-watch:0.1.0
+    build:
+      context: .
+      target: serve
+    ports: ["127.0.0.1:8787:8787"]
+    volumes: ["data:/data", "./earnings-watch.toml:/app/earnings-watch.toml:ro"]
+    read_only: true
+    cap_drop: [ALL]
+    security_opt: ["no-new-privileges:true"]
+    tmpfs: ["/tmp:mode=1777"]
+    restart: unless-stopped
+  worker:
+    image: ghcr.io/benjamin-di/earnings-watch-worker:0.1.0
+    build:
+      context: .
+      target: worker
+    volumes: ["data:/data", "./earnings-watch.toml:/app/earnings-watch.toml:ro", "cli-auth:/home/earnings"]
+    read_only: true
+    cap_drop: [ALL]
+    security_opt: ["no-new-privileges:true"]
+    tmpfs: ["/tmp:mode=1777"]
+    restart: unless-stopped
+volumes:
+  data:
+  cli-auth:

earnings_watch-0.1.0/docs/ARCHITECTURE.md

@@ -0,0 +1,19 @@
+# Architecture
+
+One SQLite database owns both shared public facts and person-scoped state. Shared tables hold sources, events, revisions, polling state and documents. Personal tables hold follows, calendar ledgers, delivery receipts and downloads. Personal access always requires an explicit person selected at the authentication boundary.
+
+CLI, MCP and Python callers share `PersonService`. It receives a read-only library reader and a personal store. The serving surface has no network, model or provider dependency. FastMCP runs synchronous service calls outside its event loop. SQL connections use WAL, five-second busy timeouts and explicit transactions; personal acknowledgements use immediate write transactions.
+
+Maintenance runs separately under one process lock. Its stages register pending issuers, capture pages, extract claims, verify evidence, reconcile facts, poll official releases and prepare personal notification outboxes. A failed or incomplete extraction cannot establish absence. Removal caps guard catalogue commits. Models and web pages cannot write directly to the database.
+
+Only `store/` imports SQLite. `transport.py` owns HTTP, including DNS validation and IP pinning with original-host TLS SNI. `llm/` owns model processes. The pure engine depends on models and the standard library. An AST gate enforces capability boundaries.
+
+Calendar plans read follows, events, revision sequence and ledger in one snapshot. A signed handle binds that snapshot, person, sink, operations and thirty-minute expiry. Acknowledgement validates the handle and revisions in the same transaction that records confirmed writes. Retries of an acknowledged handle return its original receipt.
+
+Event revisions increase across removal and reintroduction, so change consumers
+and ICS clients never see a sequence reset. Personal download receipts describe
+historical effects and survive catalogue retirement. They reference a document's
+stable identifier without requiring that document to remain in the current
+catalogue; new receipts validate current catalogue membership before insertion.
+
+The library deliberately shares public facts. A public query can reveal that a source was registered or refreshed; it never returns another person's follows, tokens or calendar ledger. Operators who need to hide interest in an issuer must use separate deployments.

earnings_watch-0.1.0/docs/DESIGN.md

@@ -0,0 +1,13 @@
+# Design decisions
+
+Earnings Watch describes the task and retains the `earnings_` MCP namespace. It combines an evidence-backed issuer calendar with document discovery; it is not a price feed or a forecast of earnings dates.
+
+The design uses three familiar patterns: a pure validation/reconciliation core, a shared catalogue with personal projections, and a durable outbox. SQLite keeps backup and installation simple for one host. A database server, built-in OAuth issuer and plugin loader would add operational boundaries without improving this workload.
+
+Model access uses user-owned agent CLIs. A raw API integration would introduce a second authentication and billing path. Extraction runs with tools disabled. Research has only search and scoped page/observation tools; page evidence must still pass deterministic validation. Browser automation is an extension boundary rather than a requirement for reading static issuer pages.
+
+Maintenance is asynchronous because requests and model subprocesses have independent deadlines. The serving service remains synchronous and bounded. This is a deliberate deviation from a synchronous-core preference: I/O orchestration lives outside the pure engine and read service.
+
+Side effects have explicit boundaries. R0 queries produce facts or plans. R1 operations update only personal state. Outbound notification delivery requires a separate notifier invocation. Calendar plan/ack delegates account effects to the client's optional Outlook app. No calendar feature grants arbitrary web content authority to invite people.
+
+A single authoritative database replaces hand-edited state files. YAML, JSON, CSV and ICS are projections. Legacy import/export supports migration rehearsal; an uncertain legacy delivery remains unknown until an operator reconciles it. A failed image rollout does not restore database state.