imap-agent-cli 0.1.6__tar.gz → 0.2.0__tar.gz

imap_agent_cli-0.2.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.2.0 - 2026-09-03
+
+- Automatically synchronize existing managed `imap` skills in the standard directory to the running CLI's newer version. No package lookup, uv refresh, or CLI update is performed.
+- Store management identity, exact CLI version, and normalized SHA-256 content integrity in `SKILL.md` YAML metadata. Migrate legacy markers and recover missing or malformed versions.
+- Preserve modified or unverifiable content with valid versions. Add `uvx imap-agent-cli skill install --force` for explicit replacement of managed content.
+- Add read-only `skill status` with JSON and plain output. Keep `install-skill`, `remove-skill`, custom directories, and removal-time `--force`.
+- Skip automatic synchronization for local source and editable builds. Custom skills require explicit updates. Updates affect future agent skill loading.
+- Replace skills atomically and preserve unrelated files during removal.

{imap_agent_cli-0.1.6 → imap_agent_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: imap-agent-cli
-Version: 0.1.6
+Version: 0.2.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
@@ -26,6 +26,8 @@ Requires-Dist: beautifulsoup4>=4.12.0
 Requires-Dist: bleach>=6.2.0
 Requires-Dist: imapclient>=3.0.0
 Requires-Dist: markdownify>=0.14.0
+Requires-Dist: packaging>=23.2
+Requires-Dist: pyyaml>=6.0
 Provides-Extra: test
 Requires-Dist: pymap>=0.36.0; extra == 'test'
 Requires-Dist: pytest>=8.0.0; extra == 'test'
@@ -44,7 +46,7 @@ It can inspect mailboxes and append messages to Drafts. It cannot send email, de
 Install or update the `imap` agent skill:
 
 ```text
-uvx imap-agent-cli install-skill
+uvx imap-agent-cli skill install
 ```
 
 Configure the default IMAP account with environment variables:
@@ -86,7 +88,7 @@ python -m pip install imap-agent-cli
 imap-agent-cli --help
 ```
 
-All command payloads are JSON on stdout. Diagnostics and errors go to stderr.
+Command payloads are JSON on stdout by default. Skill status also offers `--format plain`. Diagnostics and errors go to stderr.
 
 Use `imap-agent-cli --about` for project URL and license attribution. Use `imap-agent-cli --version` to print only the version number.
 
@@ -130,12 +132,12 @@ imap-agent-cli config check
 
 ### Agent Skill
 
-The installed skill teaches an agentic tool how to use `imap-agent-cli` safely and effectively.
+The installed skill teaches an agentic tool how to use `imap-agent-cli` safely through `uvx`.
 
 Install or update the user-scoped `imap` skill:
 
 ```text
-uvx imap-agent-cli install-skill
+uvx imap-agent-cli skill install
 ```
 
 This writes:
@@ -144,18 +146,44 @@ This writes:
 ~/.agents/skills/imap/SKILL.md
 ```
 
+Normally installed CLI builds check this location on every ordinary invocation, including help, version, and about output. An already-installed managed skill from an older CLI version is replaced only if its recorded content hash still matches. Missing skills are never installed automatically. Unmanaged skills, equal versions, and newer versions are left alone.
+
+The running CLI version is the authority. Synchronization is local. It does not query PyPI, refresh uv's cache, or update uv or the CLI. Updating those tools remains a separate action. Skill-management commands skip automatic synchronization.
+
+Inspect the installed version, content integrity, and synchronization eligibility without changing the skill:
+
+```text
+uvx imap-agent-cli skill status
+uvx imap-agent-cli skill status --format plain
+```
+
+Modified skills and skills with valid versions but missing or invalid hashes are preserved. To replace managed content explicitly:
+
+```text
+uvx imap-agent-cli skill install --force
+```
+
+Install-time `--force` still refuses unmanaged content and never downgrades a newer skill. Legacy skills with the old HTML managed marker migrate once as version 0. Missing or malformed managed versions receive a fresh replacement without a hash check. Ownership, version, and the SHA-256 content hash are stored in `SKILL.md` front matter under `metadata`. The hash detects edits. It is not a signature.
+
 Remove the managed skill:
 
 ```text
-uvx imap-agent-cli remove-skill
+uvx imap-agent-cli skill remove
 ```
 
-Use `--skills-dir PATH` to install into a nonstandard skills directory:
+Removal deletes only `SKILL.md` and removes its directory if empty. Unrelated files are kept. Removal retains `--force` for explicitly removing an unmanaged `SKILL.md`. The original `install-skill` and `remove-skill` aliases remain supported.
+
+Use `--skills-dir PATH` on any skill command to select a custom skills root. Custom locations require explicit updates and are never discovered by ordinary invocations:
 
 ```text
-uvx imap-agent-cli install-skill --skills-dir ~/.agents/skills
+uvx imap-agent-cli skill install --skills-dir ./my-skills
+uvx imap-agent-cli skill status --skills-dir ./my-skills
 ```
 
+Local checkouts, local source installs, and editable builds do not synchronize automatically. Unverifiable installation origins are also skipped. Explicit installation still works from development builds, including `uvx --from . imap-agent-cli skill install`. Installed wheels remain eligible, including wheels installed from a local file.
+
+An update affects future agent skill loading. An agent session may retain instructions it has already loaded.
+
 ### Safety Boundary
 
 Allowed:
@@ -219,6 +247,14 @@ Run no-network unit tests:
 python -m unittest discover -v
 ```
 
+To validate an installed wheel and local-source exclusions, build the package and set `IMAP_AGENT_CLI_WHEEL_TEST` to the wheel's path. Then run:
+
+```text
+python -m unittest tests.test_wheel_smoke -v
+```
+
+This opt-in check uses uv to install into a temporary environment with a temporary home directory. The regular tests also isolate skill paths from your home directory.
+
 Run the opt-in local IMAP integration test:
 
 Set `IMAP_AGENT_CLI_TEST_PYMAP=1` in your shell, then run:

{imap_agent_cli-0.1.6 → imap_agent_cli-0.2.0}/README.md

@@ -11,7 +11,7 @@ It can inspect mailboxes and append messages to Drafts. It cannot send email, de
 Install or update the `imap` agent skill:
 
 ```text
-uvx imap-agent-cli install-skill
+uvx imap-agent-cli skill install
 ```
 
 Configure the default IMAP account with environment variables:
@@ -53,7 +53,7 @@ python -m pip install imap-agent-cli
 imap-agent-cli --help
 ```
 
-All command payloads are JSON on stdout. Diagnostics and errors go to stderr.
+Command payloads are JSON on stdout by default. Skill status also offers `--format plain`. Diagnostics and errors go to stderr.
 
 Use `imap-agent-cli --about` for project URL and license attribution. Use `imap-agent-cli --version` to print only the version number.
 
@@ -97,12 +97,12 @@ imap-agent-cli config check
 
 ### Agent Skill
 
-The installed skill teaches an agentic tool how to use `imap-agent-cli` safely and effectively.
+The installed skill teaches an agentic tool how to use `imap-agent-cli` safely through `uvx`.
 
 Install or update the user-scoped `imap` skill:
 
 ```text
-uvx imap-agent-cli install-skill
+uvx imap-agent-cli skill install
 ```
 
 This writes:
@@ -111,18 +111,44 @@ This writes:
 ~/.agents/skills/imap/SKILL.md
 ```
 
+Normally installed CLI builds check this location on every ordinary invocation, including help, version, and about output. An already-installed managed skill from an older CLI version is replaced only if its recorded content hash still matches. Missing skills are never installed automatically. Unmanaged skills, equal versions, and newer versions are left alone.
+
+The running CLI version is the authority. Synchronization is local. It does not query PyPI, refresh uv's cache, or update uv or the CLI. Updating those tools remains a separate action. Skill-management commands skip automatic synchronization.
+
+Inspect the installed version, content integrity, and synchronization eligibility without changing the skill:
+
+```text
+uvx imap-agent-cli skill status
+uvx imap-agent-cli skill status --format plain
+```
+
+Modified skills and skills with valid versions but missing or invalid hashes are preserved. To replace managed content explicitly:
+
+```text
+uvx imap-agent-cli skill install --force
+```
+
+Install-time `--force` still refuses unmanaged content and never downgrades a newer skill. Legacy skills with the old HTML managed marker migrate once as version 0. Missing or malformed managed versions receive a fresh replacement without a hash check. Ownership, version, and the SHA-256 content hash are stored in `SKILL.md` front matter under `metadata`. The hash detects edits. It is not a signature.
+
 Remove the managed skill:
 
 ```text
-uvx imap-agent-cli remove-skill
+uvx imap-agent-cli skill remove
 ```
 
-Use `--skills-dir PATH` to install into a nonstandard skills directory:
+Removal deletes only `SKILL.md` and removes its directory if empty. Unrelated files are kept. Removal retains `--force` for explicitly removing an unmanaged `SKILL.md`. The original `install-skill` and `remove-skill` aliases remain supported.
+
+Use `--skills-dir PATH` on any skill command to select a custom skills root. Custom locations require explicit updates and are never discovered by ordinary invocations:
 
 ```text
-uvx imap-agent-cli install-skill --skills-dir ~/.agents/skills
+uvx imap-agent-cli skill install --skills-dir ./my-skills
+uvx imap-agent-cli skill status --skills-dir ./my-skills
 ```
 
+Local checkouts, local source installs, and editable builds do not synchronize automatically. Unverifiable installation origins are also skipped. Explicit installation still works from development builds, including `uvx --from . imap-agent-cli skill install`. Installed wheels remain eligible, including wheels installed from a local file.
+
+An update affects future agent skill loading. An agent session may retain instructions it has already loaded.
+
 ### Safety Boundary
 
 Allowed:
@@ -186,6 +212,14 @@ Run no-network unit tests:
 python -m unittest discover -v
 ```
 
+To validate an installed wheel and local-source exclusions, build the package and set `IMAP_AGENT_CLI_WHEEL_TEST` to the wheel's path. Then run:
+
+```text
+python -m unittest tests.test_wheel_smoke -v
+```
+
+This opt-in check uses uv to install into a temporary environment with a temporary home directory. The regular tests also isolate skill paths from your home directory.
+
 Run the opt-in local IMAP integration test:
 
 Set `IMAP_AGENT_CLI_TEST_PYMAP=1` in your shell, then run:

{imap_agent_cli-0.1.6 → imap_agent_cli-0.2.0}/imap_agent_cli.py

@@ -5,6 +5,8 @@
 #   "beautifulsoup4>=4.12.0",
 #   "bleach>=6.2.0",
 #   "markdownify>=0.14.0",
+#   "packaging>=23.2",
+#   "PyYAML>=6.0",
 # ]
 # ///
 """Local development wrapper for imap-agent-cli."""

{imap_agent_cli-0.1.6 → imap_agent_cli-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "imap-agent-cli"
-version = "0.1.6"
+version = "0.2.0"
 description = "Agent-first IMAP CLI for safe email search, read, attachment download, and draft creation"
 readme = "README.md"
 license = "MIT"
@@ -32,6 +32,8 @@ dependencies = [
   "beautifulsoup4>=4.12.0",
   "bleach>=6.2.0",
   "markdownify>=0.14.0",
+  "packaging>=23.2",
+  "PyYAML>=6.0",
 ]
 
 [project.optional-dependencies]

{imap_agent_cli-0.1.6 → imap_agent_cli-0.2.0}/spec.md

@@ -319,6 +319,26 @@ imap-agent-cli config add-profile work --preset generic-ssl-993 --host colo-mail
 
 All commands output JSON to stdout by default. Diagnostics and errors go to stderr.
 
+## Managed Agent Skill
+
+The distribution and command are `imap-agent-cli`. The Python import package is `imap_agent_cli`. The skill is `imap`, installed at `~/.agents/skills/imap/SKILL.md` by `uvx imap-agent-cli skill install`. The original `install-skill` and `remove-skill` commands remain aliases.
+
+`imap_agent_cli.__version__` is the runtime authority and must match `--version`. Canonical skill generation writes `metadata.managed-by: imap-agent-cli`, a quoted `metadata.managed-version`, and a quoted `metadata.managed-content-sha256` with the `sha256:` prefix and 64 lowercase hexadecimal characters. There is no top-level version or sidecar file. The bundled instructions continue to prefer `uvx`.
+
+The content hash covers the entire UTF-8 file after normalizing CRLF and CR to LF and replacing only the hash field's value with `""`. Verification uses the installed text without reserializing YAML. Generated files have LF endings, a trailing newline, and no byte order mark. This detects modifications and is not a signature.
+
+Ordinary invocations, including help, version, about, and no arguments, check only an already-installed skill in the standard location. Skill-management commands skip this check. Compare versions with PEP 440. Replace pristine older managed content. Preserve equal or newer versions and unmanaged content. Preserve older content with a missing, malformed, or mismatched hash and recommend `uvx imap-agent-cli skill install --force`.
+
+The legacy HTML marker remains recognized unless front matter assigns ownership to another tool. Legacy content without a version migrates as version 0. Missing or malformed managed versions intentionally recover through replacement without integrity verification. Newly generated metadata becomes authoritative.
+
+`skill install` creates missing skills and updates pristine older managed skills. `--force` permits replacement of altered managed content, including at the same version. It never overwrites unmanaged content or downgrades a newer version. `skill remove` manages only `SKILL.md`, keeps unrelated files, and retains its explicit force override for unmanaged files. Unexpected directories and linked skill paths are refused.
+
+`skill status` is read-only. JSON is the default, with `--format plain` available. Report path, installation and ownership, running and installed versions, version relationship, integrity, automatic eligibility, local-development exclusion, and any force recommendation. All skill commands accept `--skills-dir PATH`. Custom locations require explicit updates.
+
+Automatic synchronization excludes local checkouts, local source installations, editable builds, and unverified installation origins. Use installed-distribution file records and PEP 610 metadata. Built wheel installations remain eligible. Explicit skill commands work from development builds.
+
+Synchronization performs no package-index lookup, uv cache refresh, or CLI update. Replacement uses a flushed and closed temporary file in the target directory and an atomic replace after rechecking the installed bytes. Concurrent changes abort that attempt. Failures do not change the primary command's exit status. Notices go only to stderr. Updates apply to future skill loading and may not change instructions already loaded in an agent session.
+
 ## Folder Commands
 
 List folders:

{imap_agent_cli-0.1.6 → imap_agent_cli-0.2.0}/src/imap_agent_cli/__init__.py

@@ -1,3 +1,3 @@
 """Agent-first IMAP CLI."""
 
-__version__ = "0.1.6"
+__version__ = "0.2.0"

{imap_agent_cli-0.1.6 → imap_agent_cli-0.2.0}/src/imap_agent_cli/cli.py

@@ -12,7 +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
+from .skill import install_skill, remove_skill, skill_status, sync_skill
 
 
 PROJECT_URL = "https://github.com/pseudosavant/imap-agent-cli"
@@ -52,8 +52,9 @@ Output:
 Commands:
   config          initialize and manage profile configuration
   profiles        list configured profile names
-  install-skill   install or update the imap agent skill
-  remove-skill    remove the managed imap agent skill
+  skill           install, inspect status, or remove the imap agent skill
+  install-skill   alias for skill install
+  remove-skill    alias for skill remove
   folders         list folders
   search          search messages
   read            read a message by folder and UID
@@ -61,6 +62,14 @@ Commands:
   attachments     list or download attachments
   draft           create new or reply drafts
 
+Agent skill:
+  uvx imap-agent-cli skill install
+  uvx imap-agent-cli skill status
+  uvx imap-agent-cli skill install --force
+  Installed managed skills in ~/.agents/skills/imap synchronize to newer CLI versions.
+  Modified skills are preserved. Local development builds skip synchronization.
+  Custom locations require explicit updates with --skills-dir PATH.
+
 More help:
   imap-agent-cli <command> --help
   imap-agent-cli --about
@@ -271,15 +280,46 @@ def cmd_profiles(args: argparse.Namespace) -> int:
 
 
 def cmd_install_skill(args: argparse.Namespace) -> int:
-    write_json(install_skill(Path(args.skills_dir) if args.skills_dir else None))
+    write_json(_skill_result(args, install_skill, force=args.force))
     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))
+    write_json(_skill_result(args, remove_skill, force=args.force))
+    return 0
+
+
+def _skill_result(args: argparse.Namespace, operation: Any, **kwargs: Any) -> dict[str, Any]:
+    try:
+        return operation(Path(args.skills_dir).expanduser() if args.skills_dir else None, **kwargs)
+    except (OSError, UnicodeError) as exc:
+        raise AppError("invalid_request", "skill operation failed. Check the skill path, UTF-8 encoding, and file permissions.") from exc
+
+
+def cmd_skill_status(args: argparse.Namespace) -> int:
+    result = _skill_result(args, skill_status)
+    if args.format == "plain":
+        for key, value in result.items():
+            rendered = json.dumps(value) if value is None or isinstance(value, bool) else str(value)
+            sys.stdout.write(f"{key.replace('_', ' ')}: {rendered}\n")
+    else:
+        write_json(result)
     return 0
 
 
+def _skill_parser(parser: argparse.ArgumentParser, action: str) -> None:
+    parser.add_argument("--skills-dir", metavar="PATH", help="skills root directory (default: ~/.agents/skills). Custom locations require explicit updates")
+    if action == "install":
+        parser.add_argument("--force", action="store_true", help="replace altered managed content. Never overwrite unmanaged skills or downgrade a newer version")
+        parser.set_defaults(func=cmd_install_skill)
+    elif action == "remove":
+        parser.add_argument("--force", action="store_true", help="allow removal of an unmanaged SKILL.md. Keep unrelated files")
+        parser.set_defaults(func=cmd_remove_skill)
+    else:
+        parser.add_argument("--format", choices=["json", "plain"], default="json", help="status output format (default: json). This command never modifies the skill")
+        parser.set_defaults(func=cmd_skill_status)
+
+
 def cmd_folders(args: argparse.Namespace) -> int:
     with _session(args) as session:
         write_json(session.folders())
@@ -501,14 +541,16 @@ def build_parser() -> argparse.ArgumentParser:
     profiles = sub.add_parser("profiles", help="list configured profile names")
     profiles.set_defaults(func=cmd_profiles)
 
-    install_skill_parser = sub.add_parser("install-skill", help="install or update the imap agent 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", help="remove the managed imap agent 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)
+    skill = sub.add_parser("skill", help="manage the imap agent skill", description="Manage SKILL.md explicitly. These commands skip automatic synchronization.")
+    skill_sub = skill.add_subparsers(dest="skill_command", required=True)
+    for action, description in (
+        ("install", "install a missing skill or update pristine older managed content"),
+        ("remove", "remove SKILL.md and keep unrelated files"),
+        ("status", "inspect version, integrity, and automatic synchronization eligibility without writing"),
+    ):
+        _skill_parser(skill_sub.add_parser(action, help=description, description=description), action)
+    _skill_parser(sub.add_parser("install-skill", help="alias for skill install"), "install")
+    _skill_parser(sub.add_parser("remove-skill", help="alias for skill remove"), "remove")
 
     folders = sub.add_parser("folders", help="list folders and folder metadata")
     _common_profile_args(folders)
@@ -616,6 +658,11 @@ def build_parser() -> argparse.ArgumentParser:
 def main(argv: list[str] | None = None) -> int:
     if argv is None:
         argv = sys.argv[1:]
+    # Global options take no values. Recognize the command before argparse can
+    # exit for help or version, including help for skill-management commands.
+    command = next((arg for arg in argv if not arg.startswith("-")), None)
+    if command not in {"skill", "install-skill", "remove-skill"}:
+        sync_skill()
     if not argv or argv in (["--help"], ["-h"]):
         sys.stdout.write(TOP_LEVEL_HELP)
         return 0

imap_agent_cli-0.2.0/src/imap_agent_cli/runtime.py

@@ -0,0 +1,41 @@
+"""Identify installed code without depending on its launcher."""
+
+from __future__ import annotations
+
+import json
+from importlib import metadata
+from pathlib import Path
+from urllib.parse import urlsplit
+
+
+DISTRIBUTION_NAME = "imap-agent-cli"
+
+
+def is_local_development() -> bool:
+    """Skip local sources and code whose installed origin cannot be verified.
+
+    A local wheel is a built distribution, unlike a local source archive or
+    directory. Its PEP 610 archive metadata therefore remains eligible.
+    """
+    try:
+        distribution = metadata.distribution(DISTRIBUTION_NAME)
+        module = Path(__file__).resolve()
+        files = distribution.files or ()
+        if not any(
+            str(item).replace("\\", "/") == "imap_agent_cli/runtime.py"
+            and Path(distribution.locate_file(item)).resolve() == module
+            for item in files
+        ):
+            return True
+        direct_url = distribution.read_text("direct_url.json")
+        if direct_url is None:
+            return False
+        source = json.loads(direct_url)
+        url = urlsplit(source["url"])
+        if "dir_info" in source:
+            return True
+        if url.scheme == "file":
+            return not (url.path.lower().endswith(".whl") and isinstance(source.get("archive_info"), dict))
+        return not bool(url.scheme)
+    except (metadata.PackageNotFoundError, OSError, ValueError, KeyError, TypeError, AttributeError):
+        return True