imap-agent-cli 0.1.1__tar.gz → 0.1.2__tar.gz

{imap_agent_cli-0.1.1 → imap_agent_cli-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imap-agent-cli
-Version: 0.1.1
+Version: 0.1.2
 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
@@ -104,6 +104,32 @@ Config path:
 
 Secrets should stay in environment variables, not the config file.
 
+## Codex Skill
+
+Install or update the user-scoped Codex skill:
+
+```text
+imap-agent-cli install-skill
+```
+
+This writes:
+
+```text
+~/.agents/skills/imap/SKILL.md
+```
+
+Remove the managed skill:
+
+```text
+imap-agent-cli remove-skill
+```
+
+Use `--skills-dir PATH` to install into a nonstandard skills directory, for example:
+
+```text
+imap-agent-cli install-skill --skills-dir C:\Users\PaulEllis\.agents\skills
+```
+
 ## Safety Boundary
 
 Allowed:

{imap_agent_cli-0.1.1 → imap_agent_cli-0.1.2}/README.md

@@ -71,6 +71,32 @@ Config path:
 
 Secrets should stay in environment variables, not the config file.
 
+## Codex Skill
+
+Install or update the user-scoped Codex skill:
+
+```text
+imap-agent-cli install-skill
+```
+
+This writes:
+
+```text
+~/.agents/skills/imap/SKILL.md
+```
+
+Remove the managed skill:
+
+```text
+imap-agent-cli remove-skill
+```
+
+Use `--skills-dir PATH` to install into a nonstandard skills directory, for example:
+
+```text
+imap-agent-cli install-skill --skills-dir C:\Users\PaulEllis\.agents\skills
+```
+
 ## Safety Boundary
 
 Allowed:

{imap_agent_cli-0.1.1 → imap_agent_cli-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "imap-agent-cli"
-version = "0.1.1"
+version = "0.1.2"
 description = "Agent-first IMAP CLI for safe email search, read, attachment download, and draft creation"
 readme = "README.md"
 license = "MIT"

{imap_agent_cli-0.1.1 → imap_agent_cli-0.1.2}/src/imap_agent_cli/__init__.py

@@ -1,3 +1,3 @@
 """Agent-first IMAP CLI."""
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"

{imap_agent_cli-0.1.1 → imap_agent_cli-0.1.2}/src/imap_agent_cli/cli.py

@@ -12,6 +12,7 @@ from .errors import AppError, ConfigError
 from .imap_client import ImapSession
 from .mime import create_draft_message, header_value, parse_message
 from .render import write_error, write_json
+from .skill import install_skill, remove_skill
 
 
 def _read_json_arg(value: str) -> dict[str, Any]:
@@ -138,6 +139,16 @@ def cmd_profiles(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_install_skill(args: argparse.Namespace) -> int:
+    write_json(install_skill(Path(args.skills_dir) if args.skills_dir else None))
+    return 0
+
+
+def cmd_remove_skill(args: argparse.Namespace) -> int:
+    write_json(remove_skill(Path(args.skills_dir) if args.skills_dir else None, force=args.force))
+    return 0
+
+
 def cmd_folders(args: argparse.Namespace) -> int:
     with _session(args) as session:
         write_json(session.folders())
@@ -308,6 +319,15 @@ def build_parser() -> argparse.ArgumentParser:
     profiles = sub.add_parser("profiles")
     profiles.set_defaults(func=cmd_profiles)
 
+    install_skill_parser = sub.add_parser("install-skill")
+    install_skill_parser.add_argument("--skills-dir")
+    install_skill_parser.set_defaults(func=cmd_install_skill)
+
+    remove_skill_parser = sub.add_parser("remove-skill")
+    remove_skill_parser.add_argument("--skills-dir")
+    remove_skill_parser.add_argument("--force", action="store_true")
+    remove_skill_parser.set_defaults(func=cmd_remove_skill)
+
     folders = sub.add_parser("folders")
     _common_profile_args(folders)
     folders.set_defaults(func=cmd_folders)

imap_agent_cli-0.1.2/src/imap_agent_cli/skill.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+from .errors import AppError
+
+
+SKILL_NAME = "imap"
+MANAGED_MARKER = "<!-- managed-by: imap-agent-cli -->"
+
+
+SKILL_MD = f"""---
+name: imap
+description: Use when the user asks Codex to search, read, summarize, inspect, or draft email using the local imap-agent-cli tool. Covers safe IMAP-only email access, folder enumeration, attachment download, and draft creation; must not send, delete, move, archive, flag, label, or mark messages read/unread.
+---
+
+{MANAGED_MARKER}
+
+# IMAP Email Access
+
+Use `imap-agent-cli` for safe agentic email workflows over IMAP. The tool can search and read email, list folders, inspect/download attachments, and create drafts. It cannot send email and must not be used for destructive or metadata-mutating mailbox actions.
+
+## Safety Rules
+
+- Never send email. There is no SMTP support.
+- Never delete, move, archive, label, flag, star, mark read, or mark unread messages.
+- Prefer metadata/search before reading message bodies.
+- Do not print large or sensitive email bodies unless the user asks to see the content.
+- Use `--body-format metadata` when you only need headers and attachment metadata.
+- Use `--body-format plain` for summaries unless HTML structure matters.
+- Download attachments only when the user asks and provides or accepts an output directory.
+- Create drafts only with `draft create` or `draft reply`.
+
+## Command Form
+
+Prefer the published CLI:
+
+```powershell
+$env:UV_LINK_MODE = "copy"
+uvx --refresh-package imap-agent-cli imap-agent-cli <command>
+```
+
+If working inside the `imap-agent-cli` repository, this local form is also valid:
+
+```powershell
+uv run ./imap_agent_cli.py <command>
+```
+
+The CLI uses these environment variables for the default profile:
+
+```text
+IMAP_AGENT_CLI_HOST
+IMAP_AGENT_CLI_PORT
+IMAP_AGENT_CLI_USERNAME
+IMAP_AGENT_CLI_PASSWORD
+IMAP_AGENT_CLI_TLS
+IMAP_AGENT_CLI_DRAFTS_FOLDER
+```
+
+## Folder Listing
+
+Use this to discover folder names and Drafts naming:
+
+```powershell
+uvx --refresh-package imap-agent-cli imap-agent-cli folders
+```
+
+Return only relevant folder names/counts to the user unless they ask for the full list.
+
+## Search
+
+Search defaults to `INBOX` when no folder is provided:
+
+```powershell
+uvx --refresh-package imap-agent-cli imap-agent-cli search --folder INBOX --max-results 10
+uvx --refresh-package imap-agent-cli imap-agent-cli search --folder INBOX --subject "invoice" --max-results 10
+uvx --refresh-package imap-agent-cli imap-agent-cli search --folder INBOX --from "Justin" --max-results 10
+uvx --refresh-package imap-agent-cli imap-agent-cli search --folder INBOX --since 2026-01-01 --before 2026-02-01 --max-results 10
+```
+
+If a server-side `--from` search times out, enumerate recent messages with a bounded `--max-results` and filter locally by the returned `from` metadata.
+
+For child folders:
+
+```powershell
+uvx --refresh-package imap-agent-cli imap-agent-cli search --folder Projects --recursive --max-results 25
+```
+
+For all folders, use sparingly because large mailboxes can be slow:
+
+```powershell
+uvx --refresh-package imap-agent-cli imap-agent-cli search --all-folders --subject "contract" --max-results 25
+```
+
+## Read
+
+Read a message by folder and UID from search results:
+
+```powershell
+uvx --refresh-package imap-agent-cli imap-agent-cli read --folder INBOX --uid 12345 --body-format metadata
+uvx --refresh-package imap-agent-cli imap-agent-cli read --folder INBOX --uid 12345 --body-format plain --max-body-chars 12000
+uvx --refresh-package imap-agent-cli imap-agent-cli read --folder INBOX --uid 12345 --body-format html
+```
+
+Use `metadata` first when confirming identity, attachments, or headers. Use `plain` when summarizing. Use `html` only when formatting or links matter.
+
+## Attachments
+
+List attachment metadata:
+
+```powershell
+uvx --refresh-package imap-agent-cli imap-agent-cli attachments --folder INBOX --uid 12345
+```
+
+Download requires an explicit output directory:
+
+```powershell
+uvx --refresh-package imap-agent-cli imap-agent-cli attachments download --folder INBOX --uid 12345 --part-id 1 --output-dir C:\\tmp\\email-attachments
+uvx --refresh-package imap-agent-cli imap-agent-cli attachments download --folder INBOX --uid 12345 --all --output-dir C:\\tmp\\email-attachments
+```
+
+Report saved paths to the user.
+
+## Drafts
+
+Create a new draft:
+
+```powershell
+uvx --refresh-package imap-agent-cli imap-agent-cli draft create --to person@example.com --subject "Subject" --body "Draft body"
+```
+
+Create a reply draft from an existing message:
+
+```powershell
+uvx --refresh-package imap-agent-cli imap-agent-cli draft reply --folder INBOX --uid 12345 --body "Draft reply body"
+```
+
+For longer draft bodies, write a temporary body file and pass `--body-file`. Tell the user a draft was created; do not imply it was sent.
+
+## Output Handling
+
+All CLI payloads are JSON on stdout. Diagnostics and errors are on stderr. Parse JSON before deciding what to show the user, and summarize high-signal fields instead of dumping raw output.
+"""
+
+
+def default_skills_dir() -> Path:
+    return Path.home() / ".agents" / "skills"
+
+
+def skill_dir(skills_dir: Path | None = None) -> Path:
+    return (skills_dir or default_skills_dir()) / SKILL_NAME
+
+
+def install_skill(skills_dir: Path | None = None) -> dict[str, Any]:
+    target = skill_dir(skills_dir)
+    target.mkdir(parents=True, exist_ok=True)
+    skill_path = target / "SKILL.md"
+    previous = skill_path.read_text(encoding="utf-8") if skill_path.exists() else ""
+    updated = previous != SKILL_MD
+    skill_path.write_text(SKILL_MD, encoding="utf-8")
+    return {
+        "installed": True,
+        "updated": updated,
+        "skill": SKILL_NAME,
+        "path": str(skill_path),
+    }
+
+
+def remove_skill(skills_dir: Path | None = None, *, force: bool = False) -> dict[str, Any]:
+    target = skill_dir(skills_dir)
+    skill_path = target / "SKILL.md"
+    if not target.exists():
+        return {"removed": False, "skill": SKILL_NAME, "path": str(target), "reason": "not_installed"}
+    if not skill_path.exists():
+        raise AppError("invalid_request", f"refusing to remove '{target}' because SKILL.md is missing.")
+    content = skill_path.read_text(encoding="utf-8")
+    if MANAGED_MARKER not in content and not force:
+        raise AppError(
+            "invalid_request",
+            f"refusing to remove '{target}' because it is not marked as managed by imap-agent-cli; use --force to override.",
+        )
+    shutil.rmtree(target)
+    return {"removed": True, "skill": SKILL_NAME, "path": str(target)}

imap_agent_cli-0.1.2/tests/test_skill.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import json
+import tempfile
+import unittest
+from io import StringIO
+from pathlib import Path
+from unittest.mock import patch
+
+from tests import _bootstrap  # noqa: F401
+
+from imap_agent_cli.cli import main
+from imap_agent_cli.errors import AppError
+from imap_agent_cli.skill import MANAGED_MARKER, install_skill, remove_skill
+
+
+class SkillTests(unittest.TestCase):
+    def test_install_skill_creates_and_updates_managed_skill(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            first = install_skill(root)
+            self.assertTrue(first["installed"])
+            self.assertTrue(first["updated"])
+            skill_path = root / "imap" / "SKILL.md"
+            self.assertTrue(skill_path.exists())
+            content = skill_path.read_text(encoding="utf-8")
+            self.assertIn("name: imap", content)
+            self.assertIn(MANAGED_MARKER, content)
+            self.assertIn("draft reply", content)
+
+            second = install_skill(root)
+            self.assertTrue(second["installed"])
+            self.assertFalse(second["updated"])
+
+    def test_remove_skill_removes_only_managed_skill(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            install_skill(root)
+            removed = remove_skill(root)
+            self.assertTrue(removed["removed"])
+            self.assertFalse((root / "imap").exists())
+
+    def test_remove_skill_refuses_unmanaged_skill_without_force(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            skill_dir = root / "imap"
+            skill_dir.mkdir(parents=True)
+            (skill_dir / "SKILL.md").write_text("---\nname: imap\n---\ncustom\n", encoding="utf-8")
+            with self.assertRaises(AppError):
+                remove_skill(root)
+            removed = remove_skill(root, force=True)
+            self.assertTrue(removed["removed"])
+
+    def test_cli_install_skill_outputs_json(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            stdout = StringIO()
+            with patch("sys.stdout", stdout):
+                code = main(["install-skill", "--skills-dir", tmp])
+            self.assertEqual(code, 0)
+            payload = json.loads(stdout.getvalue())
+            self.assertEqual(payload["skill"], "imap")
+            self.assertTrue((Path(tmp) / "imap" / "SKILL.md").exists())
+
+    def test_cli_remove_skill_outputs_json(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            install_skill(Path(tmp))
+            stdout = StringIO()
+            with patch("sys.stdout", stdout):
+                code = main(["remove-skill", "--skills-dir", tmp])
+            self.assertEqual(code, 0)
+            payload = json.loads(stdout.getvalue())
+            self.assertTrue(payload["removed"])
+
+
+if __name__ == "__main__":
+    unittest.main()