conjira-cli 0.2.5__tar.gz → 0.2.6__tar.gz

{conjira_cli-0.2.5/src/conjira_cli.egg-info → conjira_cli-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: conjira-cli
-Version: 0.2.5
+Version: 0.2.6
 Summary: Unofficial agent-friendly CLI for self-hosted Confluence and Jira
 Author: quanttraderkim
 License-Expression: MIT
@@ -56,6 +56,7 @@ For report-style pages, it can also preserve a small set of Confluence-native pr
 - create or update Confluence pages from either storage HTML or Markdown
 - detect stale Markdown exports and refresh them from the live page
 - fetch and export grouped Confluence inline comment threads
+- fetch Confluence page footer comments and replies
 - upload attachments to Confluence pages
 - read Jira issues, search with JQL, inspect create metadata, create issues, and add comments
 - preview writes with `--dry-run`, then enforce them with `--allow-write` plus optional allowlists
@@ -260,7 +261,33 @@ security add-generic-password -U -s conjira-cli -a jira-prod -w "$PAT"
 unset PAT
 ```
 
-On Linux or Windows, use environment variables or token files instead of Keychain. For example:
+On Windows, use Windows Credential Manager as the closest Keychain-style path. Keep `local/agent.env` non-secret, remove or comment out `CONFLUENCE_PAT_KEYCHAIN_*` and `JIRA_PAT_KEYCHAIN_*`, then load PATs into the current PowerShell session right before running `conjira`.
+
+Set up the PowerShell `CredentialManager` module and store the PATs once:
+
+```powershell
+Install-Module CredentialManager -Scope CurrentUser
+
+$cred = Get-Credential -UserName confluence-prod -Message "Enter Confluence PAT as password"
+New-StoredCredential -Target "conjira-cli/confluence-prod" -UserName $cred.UserName -Password $cred.GetNetworkCredential().Password -Persist LocalMachine
+Remove-Variable cred
+
+$cred = Get-Credential -UserName jira-prod -Message "Enter Jira PAT as password"
+New-StoredCredential -Target "conjira-cli/jira-prod" -UserName $cred.UserName -Password $cred.GetNetworkCredential().Password -Persist LocalMachine
+Remove-Variable cred
+```
+
+Before running the CLI in a new PowerShell session, read those credentials into environment variables. The values only live in that session:
+
+```powershell
+$env:CONFLUENCE_PAT = (Get-StoredCredential -Target "conjira-cli/confluence-prod").GetNetworkCredential().Password
+$env:JIRA_PAT = (Get-StoredCredential -Target "conjira-cli/jira-prod").GetNetworkCredential().Password
+
+conjira --env-file .\local\agent.env auth-check
+conjira --env-file .\local\agent.env jira-auth-check
+```
+
+If Windows Credential Manager is unavailable, or on Linux, use environment variables or token files instead. For example:
 
 ```dotenv
 CONFLUENCE_BASE_URL=https://confluence.example.com
@@ -318,6 +345,12 @@ Export grouped inline comment threads:
 conjira --env-file ./local/agent.env export-inline-comments-md --page-id 123456 --status open --output-dir "/path/to/work-folder"
 ```
 
+Read page footer comments and replies:
+
+```bash
+conjira --env-file ./local/agent.env get-footer-comments --page-id 123456
+```
+
 Create or update a Confluence page:
 
 ```bash
@@ -413,6 +446,17 @@ Jira settings:
 - `JIRA_ALLOWED_PROJECT_KEYS`
 - `JIRA_ALLOWED_ISSUE_KEYS`
 
+Shared rate-limit settings:
+
+- `CONJIRA_RATE_LIMIT_ENABLED`: set to `false` to disable client-side throttling
+- `CONJIRA_RATE_LIMIT_RPS`: default `4.0`
+- `CONJIRA_RATE_LIMIT_BURST`: default `8`
+- `CONJIRA_MAX_RETRIES`: default `5` retries after the first failed request
+- `CONJIRA_RETRY_BASE_SECONDS`: default `1.0`
+- `CONJIRA_RETRY_MAX_SECONDS`: default `30.0`
+
+Product-specific overrides such as `CONFLUENCE_RATE_LIMIT_RPS` and `JIRA_RATE_LIMIT_RPS` take precedence over the shared `CONJIRA_*` values. The throttle state is shared across local CLI processes for the same product, base URL, and token, so separate agent calls are paced together.
+
 ## Safety model
 
 This CLI intentionally does not implement delete commands for Confluence pages or Jira issues.
@@ -429,7 +473,8 @@ When the CLI hits a common API failure, it now returns a `guidance` field alongs
 - `403`: check product permissions and any configured allowlists
 - `404`: check the page ID, issue key, or target path and confirm the PAT owner can see it in the web UI
 - `409`: refresh live content and retry, especially for Confluence updates after concurrent edits
-- `429` and `5xx`: retry after a short delay and reduce request volume if you are looping
+- `429`: the CLI automatically retries with backoff and honors `Retry-After` when the server sends it
+- `5xx`: retry after a short delay and reduce request volume if you are looping
 
 ## Export strategy
 

{conjira_cli-0.2.5 → conjira_cli-0.2.6}/README.md

@@ -27,6 +27,7 @@ For report-style pages, it can also preserve a small set of Confluence-native pr
 - create or update Confluence pages from either storage HTML or Markdown
 - detect stale Markdown exports and refresh them from the live page
 - fetch and export grouped Confluence inline comment threads
+- fetch Confluence page footer comments and replies
 - upload attachments to Confluence pages
 - read Jira issues, search with JQL, inspect create metadata, create issues, and add comments
 - preview writes with `--dry-run`, then enforce them with `--allow-write` plus optional allowlists
@@ -231,7 +232,33 @@ security add-generic-password -U -s conjira-cli -a jira-prod -w "$PAT"
 unset PAT
 ```
 
-On Linux or Windows, use environment variables or token files instead of Keychain. For example:
+On Windows, use Windows Credential Manager as the closest Keychain-style path. Keep `local/agent.env` non-secret, remove or comment out `CONFLUENCE_PAT_KEYCHAIN_*` and `JIRA_PAT_KEYCHAIN_*`, then load PATs into the current PowerShell session right before running `conjira`.
+
+Set up the PowerShell `CredentialManager` module and store the PATs once:
+
+```powershell
+Install-Module CredentialManager -Scope CurrentUser
+
+$cred = Get-Credential -UserName confluence-prod -Message "Enter Confluence PAT as password"
+New-StoredCredential -Target "conjira-cli/confluence-prod" -UserName $cred.UserName -Password $cred.GetNetworkCredential().Password -Persist LocalMachine
+Remove-Variable cred
+
+$cred = Get-Credential -UserName jira-prod -Message "Enter Jira PAT as password"
+New-StoredCredential -Target "conjira-cli/jira-prod" -UserName $cred.UserName -Password $cred.GetNetworkCredential().Password -Persist LocalMachine
+Remove-Variable cred
+```
+
+Before running the CLI in a new PowerShell session, read those credentials into environment variables. The values only live in that session:
+
+```powershell
+$env:CONFLUENCE_PAT = (Get-StoredCredential -Target "conjira-cli/confluence-prod").GetNetworkCredential().Password
+$env:JIRA_PAT = (Get-StoredCredential -Target "conjira-cli/jira-prod").GetNetworkCredential().Password
+
+conjira --env-file .\local\agent.env auth-check
+conjira --env-file .\local\agent.env jira-auth-check
+```
+
+If Windows Credential Manager is unavailable, or on Linux, use environment variables or token files instead. For example:
 
 ```dotenv
 CONFLUENCE_BASE_URL=https://confluence.example.com
@@ -289,6 +316,12 @@ Export grouped inline comment threads:
 conjira --env-file ./local/agent.env export-inline-comments-md --page-id 123456 --status open --output-dir "/path/to/work-folder"
 ```
 
+Read page footer comments and replies:
+
+```bash
+conjira --env-file ./local/agent.env get-footer-comments --page-id 123456
+```
+
 Create or update a Confluence page:
 
 ```bash
@@ -384,6 +417,17 @@ Jira settings:
 - `JIRA_ALLOWED_PROJECT_KEYS`
 - `JIRA_ALLOWED_ISSUE_KEYS`
 
+Shared rate-limit settings:
+
+- `CONJIRA_RATE_LIMIT_ENABLED`: set to `false` to disable client-side throttling
+- `CONJIRA_RATE_LIMIT_RPS`: default `4.0`
+- `CONJIRA_RATE_LIMIT_BURST`: default `8`
+- `CONJIRA_MAX_RETRIES`: default `5` retries after the first failed request
+- `CONJIRA_RETRY_BASE_SECONDS`: default `1.0`
+- `CONJIRA_RETRY_MAX_SECONDS`: default `30.0`
+
+Product-specific overrides such as `CONFLUENCE_RATE_LIMIT_RPS` and `JIRA_RATE_LIMIT_RPS` take precedence over the shared `CONJIRA_*` values. The throttle state is shared across local CLI processes for the same product, base URL, and token, so separate agent calls are paced together.
+
 ## Safety model
 
 This CLI intentionally does not implement delete commands for Confluence pages or Jira issues.
@@ -400,7 +444,8 @@ When the CLI hits a common API failure, it now returns a `guidance` field alongs
 - `403`: check product permissions and any configured allowlists
 - `404`: check the page ID, issue key, or target path and confirm the PAT owner can see it in the web UI
 - `409`: refresh live content and retry, especially for Confluence updates after concurrent edits
-- `429` and `5xx`: retry after a short delay and reduce request volume if you are looping
+- `429`: the CLI automatically retries with backoff and honors `Retry-After` when the server sends it
+- `5xx`: retry after a short delay and reduce request volume if you are looping
 
 ## Export strategy
 

{conjira_cli-0.2.5 → conjira_cli-0.2.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "conjira-cli"
-version = "0.2.5"
+version = "0.2.6"
 description = "Unofficial agent-friendly CLI for self-hosted Confluence and Jira"
 readme = "README.md"
 requires-python = ">=3.9"

{conjira_cli-0.2.5 → conjira_cli-0.2.6}/src/conjira_cli/__init__.py

@@ -1,3 +1,3 @@
 __all__ = ["__version__"]
 
-__version__ = "0.2.4"
+__version__ = "0.2.6"

{conjira_cli-0.2.5 → conjira_cli-0.2.6}/src/conjira_cli/cli.py

@@ -49,6 +49,12 @@ def _read_text_arg(raw_text: Optional[str], file_path: Optional[str]) -> str:
     return ""
 
 
+def _normalize_id(value: str) -> str:
+    # Strip whitespace and trailing slashes so URL-derived IDs like
+    # "1025003939/" (from a pasted Confluence URL) don't break path joins.
+    return value.strip().strip("/")
+
+
 def _read_json_arg(raw_json: Optional[str], file_path: Optional[str]) -> Dict[str, Any]:
     if raw_json is not None:
         return json.loads(raw_json)
@@ -303,14 +309,14 @@ def _build_parser() -> argparse.ArgumentParser:
     subparsers.add_parser("auth-check", help="Validate Confluence base URL and PAT")
 
     get_page = subparsers.add_parser("get-page", help="Fetch a Confluence page by ID")
-    get_page.add_argument("--page-id", required=True)
+    get_page.add_argument("--page-id", required=True, type=_normalize_id)
     get_page.add_argument("--expand")
 
     export_page_md = subparsers.add_parser(
         "export-page-md",
         help="Export a Confluence page to a Markdown file",
     )
-    export_page_md.add_argument("--page-id", required=True)
+    export_page_md.add_argument("--page-id", required=True, type=_normalize_id)
     export_page_md.add_argument("--output-file")
     export_page_md.add_argument("--output-dir")
     export_page_md.add_argument("--filename")
@@ -320,7 +326,7 @@ def _build_parser() -> argparse.ArgumentParser:
         "export-tree-md",
         help="Export a Confluence page tree to nested Markdown folders",
     )
-    export_tree_md.add_argument("--page-id", required=True)
+    export_tree_md.add_argument("--page-id", required=True, type=_normalize_id)
     export_tree_md.add_argument("--output-dir")
     export_tree_md.add_argument("--staging-local", action="store_true")
 
@@ -340,7 +346,7 @@ def _build_parser() -> argparse.ArgumentParser:
         "get-inline-comments",
         help="Fetch Confluence inline comments and group them into threads",
     )
-    get_inline_comments.add_argument("--page-id", required=True)
+    get_inline_comments.add_argument("--page-id", required=True, type=_normalize_id)
     get_inline_comments.add_argument("--limit", type=int, default=200)
     get_inline_comments.add_argument(
         "--status",
@@ -348,11 +354,19 @@ def _build_parser() -> argparse.ArgumentParser:
         default="all",
     )
 
+    get_footer_comments = subparsers.add_parser(
+        "get-footer-comments",
+        aliases=["get-page-comments"],
+        help="Fetch Confluence page footer comments, including replies",
+    )
+    get_footer_comments.add_argument("--page-id", required=True)
+    get_footer_comments.add_argument("--limit", type=int, default=200)
+
     export_inline_comments_md = subparsers.add_parser(
         "export-inline-comments-md",
         help="Export grouped Confluence inline comments to a Markdown file",
     )
-    export_inline_comments_md.add_argument("--page-id", required=True)
+    export_inline_comments_md.add_argument("--page-id", required=True, type=_normalize_id)
     export_inline_comments_md.add_argument("--limit", type=int, default=200)
     export_inline_comments_md.add_argument(
         "--status",
@@ -377,7 +391,7 @@ def _build_parser() -> argparse.ArgumentParser:
     create_page_body_group.add_argument("--body-markdown-file")
 
     update_page = subparsers.add_parser("update-page", help="Update an existing Confluence page")
-    update_page.add_argument("--page-id", required=True)
+    update_page.add_argument("--page-id", required=True, type=_normalize_id)
     update_page.add_argument("--allow-write", action="store_true")
     update_page.add_argument("--dry-run", action="store_true")
     update_page.add_argument("--title")
@@ -396,7 +410,7 @@ def _build_parser() -> argparse.ArgumentParser:
         "replace-section",
         help="Replace the content under a specific Confluence heading",
     )
-    replace_section.add_argument("--page-id", required=True)
+    replace_section.add_argument("--page-id", required=True, type=_normalize_id)
     replace_section.add_argument("--heading", required=True)
     replace_section.add_argument("--allow-write", action="store_true")
     replace_section.add_argument("--dry-run", action="store_true")
@@ -410,7 +424,7 @@ def _build_parser() -> argparse.ArgumentParser:
         "insert-after-heading",
         help="Insert content immediately after a specific Confluence heading",
     )
-    insert_after_heading.add_argument("--page-id", required=True)
+    insert_after_heading.add_argument("--page-id", required=True, type=_normalize_id)
     insert_after_heading.add_argument("--heading", required=True)
     insert_after_heading.add_argument("--allow-write", action="store_true")
     insert_after_heading.add_argument("--dry-run", action="store_true")
@@ -426,7 +440,7 @@ def _build_parser() -> argparse.ArgumentParser:
         "move-page",
         help="Move an existing Confluence page under a different parent page",
     )
-    move_page.add_argument("--page-id", required=True)
+    move_page.add_argument("--page-id", required=True, type=_normalize_id)
     move_page.add_argument("--new-parent-id", required=True)
     move_page.add_argument("--allow-write", action="store_true")
     move_page.add_argument("--dry-run", action="store_true")
@@ -435,7 +449,7 @@ def _build_parser() -> argparse.ArgumentParser:
         "upload-attachment",
         help="Upload or update a Confluence attachment on a page",
     )
-    upload_attachment.add_argument("--page-id", required=True)
+    upload_attachment.add_argument("--page-id", required=True, type=_normalize_id)
     upload_attachment.add_argument("--file", required=True)
     upload_attachment.add_argument("--comment")
     upload_attachment.add_argument("--allow-write", action="store_true")
@@ -451,7 +465,7 @@ def _build_parser() -> argparse.ArgumentParser:
     subparsers.add_parser("jira-auth-check", help="Validate Jira base URL and PAT")
 
     jira_get_issue = subparsers.add_parser("jira-get-issue", help="Fetch a Jira issue by key")
-    jira_get_issue.add_argument("--issue-key", required=True)
+    jira_get_issue.add_argument("--issue-key", required=True, type=_normalize_id)
     jira_get_issue.add_argument("--fields")
     jira_get_issue.add_argument("--expand")
     jira_get_issue.add_argument("--include-comments", action="store_true")
@@ -488,7 +502,7 @@ def _build_parser() -> argparse.ArgumentParser:
     jira_create_issue_fields_group.add_argument("--fields-file")
 
     jira_add_comment = subparsers.add_parser("jira-add-comment", help="Add a Jira issue comment")
-    jira_add_comment.add_argument("--issue-key", required=True)
+    jira_add_comment.add_argument("--issue-key", required=True, type=_normalize_id)
     jira_add_comment.add_argument("--allow-write", action="store_true")
     jira_add_comment.add_argument("--dry-run", action="store_true")
     jira_comment_group = jira_add_comment.add_mutually_exclusive_group(required=True)
@@ -923,6 +937,12 @@ def _handle_confluence(args: argparse.Namespace) -> Dict[str, Any]:
         base_url=settings.base_url,
         token=settings.token,
         timeout_seconds=settings.timeout_seconds,
+        rate_limit_enabled=settings.rate_limit_enabled,
+        rate_limit_rps=settings.rate_limit_rps,
+        rate_limit_burst=settings.rate_limit_burst,
+        max_retries=settings.max_retries,
+        retry_base_seconds=settings.retry_base_seconds,
+        retry_max_seconds=settings.retry_max_seconds,
     )
 
     if args.command == "auth-check":
@@ -1074,6 +1094,16 @@ def _handle_confluence(args: argparse.Namespace) -> Dict[str, Any]:
             comments=comments,
             status_filter=args.status,
         )
+    if args.command in {"get-footer-comments", "get-page-comments"}:
+        page = client.get_page(args.page_id, expand="version,space")
+        comments = client.list_footer_comments(
+            args.page_id,
+            limit=args.limit,
+        )
+        return client.summarize_footer_comments(
+            page=page,
+            comments=comments,
+        )
     if args.command == "export-inline-comments-md":
         page = client.get_page(args.page_id, expand="version,space")
         comments = client.list_inline_comments(
@@ -1376,6 +1406,12 @@ def _handle_jira(args: argparse.Namespace) -> Dict[str, Any]:
         base_url=settings.base_url,
         token=settings.token,
         timeout_seconds=settings.timeout_seconds,
+        rate_limit_enabled=settings.rate_limit_enabled,
+        rate_limit_rps=settings.rate_limit_rps,
+        rate_limit_burst=settings.rate_limit_burst,
+        max_retries=settings.max_retries,
+        retry_base_seconds=settings.retry_base_seconds,
+        retry_max_seconds=settings.retry_max_seconds,
     )
 
     if args.command == "jira-auth-check":