imap-agent-cli 0.1.0__tar.gz

imap_agent_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build
+        run: uv build --no-sources
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish distributions to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

imap_agent_cli-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tmp/
+test-output/
+uv.lock

imap_agent_cli-0.1.0/LICENSE

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

imap_agent_cli-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: imap-agent-cli
+Version: 0.1.0
+Summary: Agent-first IMAP CLI for safe email search, read, attachment download, and draft creation
+Project-URL: Homepage, https://github.com/pseudosavant/imap-agent-cli
+Project-URL: Repository, https://github.com/pseudosavant/imap-agent-cli
+Project-URL: Issues, https://github.com/pseudosavant/imap-agent-cli/issues
+Author: Paul
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,cli,drafts,email,imap
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Communications :: Email :: Post-Office :: IMAP
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: bleach>=6.2.0
+Requires-Dist: imapclient>=3.0.0
+Requires-Dist: markdownify>=0.14.0
+Provides-Extra: test
+Requires-Dist: pymap>=0.36.0; extra == 'test'
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# imap-agent-cli
+
+`imap-agent-cli` is an agent-first IMAP CLI for safe email search, read, attachment download, and draft creation.
+
+It can inspect mailboxes and append messages to Drafts. It cannot send email, delete messages, move messages, archive messages, change labels, alter flags, or mark messages read/unread.
+
+## Status
+
+This repo is under active development. The behavior target is defined in [`spec.md`](./spec.md).
+
+## Quick Start
+
+Single-profile env-var setup:
+
+```text
+IMAP_AGENT_CLI_HOST=imap.example.com
+IMAP_AGENT_CLI_PORT=993
+IMAP_AGENT_CLI_USERNAME=me@example.com
+IMAP_AGENT_CLI_PASSWORD=...
+IMAP_AGENT_CLI_TLS=true
+```
+
+Local development:
+
+```text
+uv run ./imap_agent_cli.py --help
+uv run ./imap_agent_cli.py folders
+uv run ./imap_agent_cli.py search --subject invoice
+```
+
+Packaged execution:
+
+```text
+uvx imap-agent-cli --help
+```
+
+## Examples
+
+```text
+imap-agent-cli folders
+imap-agent-cli search --folder INBOX --subject "invoice" --max-results 10
+imap-agent-cli read --folder INBOX --uid 12345 --body-format html
+imap-agent-cli attachments --folder INBOX --uid 12345
+imap-agent-cli attachments download --folder INBOX --uid 12345 --part-id 2 --output-dir C:\tmp\email-attachments
+imap-agent-cli draft create --to person@example.com --subject "Hello" --body "Draft only."
+imap-agent-cli draft reply --folder INBOX --uid 12345 --body "Thanks. I will review this."
+```
+
+All command payloads are JSON on stdout. Diagnostics and errors go to stderr.
+
+## Config
+
+Create a starter config:
+
+```text
+imap-agent-cli config init
+```
+
+Add a named profile:
+
+```text
+imap-agent-cli config add-profile work --host imap.example.com --port 993 --username me@example.com --password-env IMAP_AGENT_CLI_WORK_PASSWORD
+imap-agent-cli config set-default-profile work
+```
+
+Config path:
+
+```text
+~/.imap-agent-cli/config.toml
+```
+
+Secrets should stay in environment variables, not the config file.
+
+## Safety Boundary
+
+Allowed:
+
+- list folders
+- search messages
+- read messages with no-seen fetch behavior
+- list/download attachments only when requested
+- append new messages to Drafts
+
+Not allowed:
+
+- send
+- delete
+- move
+- archive
+- flag/star
+- mark read/unread
+- create/delete/rename folders
+
+## Testing
+
+No-network unit tests:
+
+```text
+python -m unittest discover -v
+```
+
+Package build:
+
+```text
+uv build --no-sources
+```
+
+The spec targets `pymap` for future local IMAP integration tests on Windows without Docker.
+
+Opt-in local IMAP integration test:
+
+```text
+$env:IMAP_AGENT_CLI_TEST_PYMAP = "1"
+uv run --extra test python -m unittest tests.test_pymap_integration -v
+```
+
+The integration test starts `pymap dict --demo-data` locally and logs in with `demouser` / `demopass`.
+
+## Publishing
+
+The GitHub Actions workflow is `.github/workflows/publish.yml`.
+
+PyPI Trusted Publishing values:
+
+```text
+Project: imap-agent-cli
+Owner: pseudosavant
+Repository: imap-agent-cli
+Workflow: publish.yml
+Environment: pypi
+```

imap_agent_cli-0.1.0/README.md

@@ -0,0 +1,131 @@
+# imap-agent-cli
+
+`imap-agent-cli` is an agent-first IMAP CLI for safe email search, read, attachment download, and draft creation.
+
+It can inspect mailboxes and append messages to Drafts. It cannot send email, delete messages, move messages, archive messages, change labels, alter flags, or mark messages read/unread.
+
+## Status
+
+This repo is under active development. The behavior target is defined in [`spec.md`](./spec.md).
+
+## Quick Start
+
+Single-profile env-var setup:
+
+```text
+IMAP_AGENT_CLI_HOST=imap.example.com
+IMAP_AGENT_CLI_PORT=993
+IMAP_AGENT_CLI_USERNAME=me@example.com
+IMAP_AGENT_CLI_PASSWORD=...
+IMAP_AGENT_CLI_TLS=true
+```
+
+Local development:
+
+```text
+uv run ./imap_agent_cli.py --help
+uv run ./imap_agent_cli.py folders
+uv run ./imap_agent_cli.py search --subject invoice
+```
+
+Packaged execution:
+
+```text
+uvx imap-agent-cli --help
+```
+
+## Examples
+
+```text
+imap-agent-cli folders
+imap-agent-cli search --folder INBOX --subject "invoice" --max-results 10
+imap-agent-cli read --folder INBOX --uid 12345 --body-format html
+imap-agent-cli attachments --folder INBOX --uid 12345
+imap-agent-cli attachments download --folder INBOX --uid 12345 --part-id 2 --output-dir C:\tmp\email-attachments
+imap-agent-cli draft create --to person@example.com --subject "Hello" --body "Draft only."
+imap-agent-cli draft reply --folder INBOX --uid 12345 --body "Thanks. I will review this."
+```
+
+All command payloads are JSON on stdout. Diagnostics and errors go to stderr.
+
+## Config
+
+Create a starter config:
+
+```text
+imap-agent-cli config init
+```
+
+Add a named profile:
+
+```text
+imap-agent-cli config add-profile work --host imap.example.com --port 993 --username me@example.com --password-env IMAP_AGENT_CLI_WORK_PASSWORD
+imap-agent-cli config set-default-profile work
+```
+
+Config path:
+
+```text
+~/.imap-agent-cli/config.toml
+```
+
+Secrets should stay in environment variables, not the config file.
+
+## Safety Boundary
+
+Allowed:
+
+- list folders
+- search messages
+- read messages with no-seen fetch behavior
+- list/download attachments only when requested
+- append new messages to Drafts
+
+Not allowed:
+
+- send
+- delete
+- move
+- archive
+- flag/star
+- mark read/unread
+- create/delete/rename folders
+
+## Testing
+
+No-network unit tests:
+
+```text
+python -m unittest discover -v
+```
+
+Package build:
+
+```text
+uv build --no-sources
+```
+
+The spec targets `pymap` for future local IMAP integration tests on Windows without Docker.
+
+Opt-in local IMAP integration test:
+
+```text
+$env:IMAP_AGENT_CLI_TEST_PYMAP = "1"
+uv run --extra test python -m unittest tests.test_pymap_integration -v
+```
+
+The integration test starts `pymap dict --demo-data` locally and logs in with `demouser` / `demopass`.
+
+## Publishing
+
+The GitHub Actions workflow is `.github/workflows/publish.yml`.
+
+PyPI Trusted Publishing values:
+
+```text
+Project: imap-agent-cli
+Owner: pseudosavant
+Repository: imap-agent-cli
+Workflow: publish.yml
+Environment: pypi
+```

imap_agent_cli-0.1.0/imap_agent_cli.py

@@ -0,0 +1,30 @@
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#   "IMAPClient>=3.0.0",
+#   "beautifulsoup4>=4.12.0",
+#   "bleach>=6.2.0",
+#   "markdownify>=0.14.0",
+# ]
+# ///
+"""Local development wrapper for imap-agent-cli."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parent
+SRC = ROOT / "src"
+if str(SRC) not in sys.path:
+    sys.path.insert(0, str(SRC))
+shadow = sys.modules.get("imap_agent_cli")
+if shadow is not None and not hasattr(shadow, "__path__"):
+    del sys.modules["imap_agent_cli"]
+
+from imap_agent_cli.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

imap_agent_cli-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "imap-agent-cli"
+version = "0.1.0"
+description = "Agent-first IMAP CLI for safe email search, read, attachment download, and draft creation"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+  { name = "Paul" },
+]
+keywords = ["imap", "email", "cli", "agent", "drafts"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Communications :: Email",
+  "Topic :: Communications :: Email :: Post-Office :: IMAP",
+  "Topic :: Utilities",
+]
+dependencies = [
+  "IMAPClient>=3.0.0",
+  "beautifulsoup4>=4.12.0",
+  "bleach>=6.2.0",
+  "markdownify>=0.14.0",
+]
+
+[project.optional-dependencies]
+test = [
+  "pymap>=0.36.0",
+  "pytest>=8.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/pseudosavant/imap-agent-cli"
+Repository = "https://github.com/pseudosavant/imap-agent-cli"
+Issues = "https://github.com/pseudosavant/imap-agent-cli/issues"
+
+[project.scripts]
+imap-agent-cli = "imap_agent_cli.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/imap_agent_cli"]