jira2cli 0.1.0__tar.gz

jira2cli-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.3
+Name: jira2cli
+Version: 0.1.0
+Summary: CLI for Jira AI integrations powered by jira2ai-core
+Author: en-ver
+Requires-Dist: jira2ai-core==0.1.0
+Requires-Dist: typer>=0.16.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# jira2cli
+
+CLI adapter for Jira Cloud, powered by `jira2ai-core`.
+
+`jira2cli` is currently intended for local and development use from this workspace. Do not assume a published `uvx` or PyPI install path yet.
+
+## Environment
+
+`jira2cli` uses the same Jira credentials as `jira2mcp`:
+
+| Variable | Description |
+|---|---|
+| `JIRA_URL` | Your Jira instance URL |
+| `JIRA_USER` | Your Jira account email |
+| `JIRA_API_TOKEN` | Your Jira API token |
+
+Example:
+
+```bash
+export JIRA_URL="https://yourcompany.atlassian.net"
+export JIRA_USER="you@company.com"
+export JIRA_API_TOKEN="your-api-token"
+```
+
+## Local usage
+
+From the workspace root:
+
+```bash
+uv sync --all-packages --group dev
+uv run --package jira2cli jira2cli --help
+uv run --package jira2cli jira2cli read PROJ-123
+uv run --package jira2cli jira2cli search 'project = PROJ ORDER BY updated DESC'
+uv run --package jira2cli jira2cli fields --project-key PROJ
+```
+
+## Workspace layout
+
+- `packages/jira2ai-core` — shared operations.
+- `packages/jira2mcp` — MCP adapter published as `jira2mcp`.
+- `packages/jira2cli` — CLI adapter package.
+
+For MCP installs and Claude setup, use `uvx jira2mcp` and `claude mcp add jira -- uvx jira2mcp` as documented in the repository root README.
+
+## Maintainers
+
+Do not assume `uvx jira2cli` or `pip install jira2cli` is available yet. Keep using local workspace commands until the release gates in the maintainer docs are completed.
+
+Release sequencing, package tags, and Trusted Publishing boundaries:
+
+- <https://github.com/en-ver/jira2ai/blob/main/docs/releasing.md>
+- <https://github.com/en-ver/jira2ai/blob/main/CONTRIBUTING.md>

jira2cli-0.1.0/README.md

@@ -0,0 +1,52 @@
+# jira2cli
+
+CLI adapter for Jira Cloud, powered by `jira2ai-core`.
+
+`jira2cli` is currently intended for local and development use from this workspace. Do not assume a published `uvx` or PyPI install path yet.
+
+## Environment
+
+`jira2cli` uses the same Jira credentials as `jira2mcp`:
+
+| Variable | Description |
+|---|---|
+| `JIRA_URL` | Your Jira instance URL |
+| `JIRA_USER` | Your Jira account email |
+| `JIRA_API_TOKEN` | Your Jira API token |
+
+Example:
+
+```bash
+export JIRA_URL="https://yourcompany.atlassian.net"
+export JIRA_USER="you@company.com"
+export JIRA_API_TOKEN="your-api-token"
+```
+
+## Local usage
+
+From the workspace root:
+
+```bash
+uv sync --all-packages --group dev
+uv run --package jira2cli jira2cli --help
+uv run --package jira2cli jira2cli read PROJ-123
+uv run --package jira2cli jira2cli search 'project = PROJ ORDER BY updated DESC'
+uv run --package jira2cli jira2cli fields --project-key PROJ
+```
+
+## Workspace layout
+
+- `packages/jira2ai-core` — shared operations.
+- `packages/jira2mcp` — MCP adapter published as `jira2mcp`.
+- `packages/jira2cli` — CLI adapter package.
+
+For MCP installs and Claude setup, use `uvx jira2mcp` and `claude mcp add jira -- uvx jira2mcp` as documented in the repository root README.
+
+## Maintainers
+
+Do not assume `uvx jira2cli` or `pip install jira2cli` is available yet. Keep using local workspace commands until the release gates in the maintainer docs are completed.
+
+Release sequencing, package tags, and Trusted Publishing boundaries:
+
+- <https://github.com/en-ver/jira2ai/blob/main/docs/releasing.md>
+- <https://github.com/en-ver/jira2ai/blob/main/CONTRIBUTING.md>

jira2cli-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "jira2cli"
+version = "0.1.0"
+description = "CLI for Jira AI integrations powered by jira2ai-core"
+readme = "README.md"
+authors = [
+    { name = "en-ver" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "jira2ai-core==0.1.0",
+    "typer>=0.16.0",
+]
+
+[tool.uv.sources]
+jira2ai-core = { workspace = true }
+
+[project.scripts]
+jira2cli = "jira2cli:main"
+
+[build-system]
+requires = ["uv_build>=0.10.4,<0.11.0"]
+build-backend = "uv_build"

jira2cli-0.1.0/src/jira2cli/__init__.py

@@ -0,0 +1,7 @@
+"""CLI package for Jira AI integrations."""
+
+from .cli import app, main
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__", "app", "main"]

jira2cli-0.1.0/src/jira2cli/cli.py

@@ -0,0 +1,26 @@
+"""Typer application for jira2cli."""
+
+from __future__ import annotations
+
+import typer
+
+from .commands import register_commands
+
+app = typer.Typer(
+    name="jira2cli",
+    help="Jira CLI powered by jira2ai-core.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+register_commands(app)
+
+
+@app.callback()
+def callback() -> None:
+    """Jira CLI powered by jira2ai-core."""
+
+
+def main() -> None:
+    """Run the jira2cli application."""
+    app()

jira2cli-0.1.0/src/jira2cli/commands/__init__.py

@@ -0,0 +1,25 @@
+"""Command registration for jira2cli."""
+
+from __future__ import annotations
+
+import typer
+
+from .attachments import register_attachment_commands
+from .links import register_link_commands
+from .metadata import register_metadata_commands
+from .read import register_read_commands
+from .search import register_search_commands
+from .write import register_write_commands
+
+
+def register_commands(app: typer.Typer) -> None:
+    """Register jira2cli commands on the root Typer app."""
+    register_read_commands(app)
+    register_search_commands(app)
+    register_metadata_commands(app)
+    register_write_commands(app)
+    register_link_commands(app)
+    register_attachment_commands(app)
+
+
+__all__ = ["register_commands"]

jira2cli-0.1.0/src/jira2cli/commands/attachments.py

@@ -0,0 +1,45 @@
+"""Attachment-download jira2cli commands."""
+
+from __future__ import annotations
+
+import typer
+from jira2ai_core import client
+from jira2ai_core.operations import attachments as attachment_operations
+
+from jira2cli.output import raise_cli_exception
+
+
+def attachment_command(
+    attachment_id: str = typer.Argument(..., help="Attachment ID (e.g. 63899)"),
+    output_path: str | None = typer.Option(
+        None,
+        "--output-path",
+        help=(
+            "Path to save the attachment. Can be a directory or a full file path. "
+            "Defaults to the current directory."
+        ),
+    ),
+) -> None:
+    """Download a Jira attachment by its ID."""
+    try:
+        attachment_operations.validate_attachment_id(attachment_id)
+        api = client.get_api()
+        plan = attachment_operations.plan_attachment_download(
+            attachment_id,
+            output_path=output_path,
+            api=api,
+        )
+        attachment_operations.download_attachment_content(plan, api=api)
+        output = attachment_operations.format_attachment_download_result(plan)
+    except Exception as exc:
+        raise_cli_exception(exc)
+
+    typer.echo(output)
+
+
+def register_attachment_commands(app: typer.Typer) -> None:
+    """Register attachment-download commands."""
+    app.command("attachment")(attachment_command)
+
+
+__all__ = ["attachment_command", "register_attachment_commands"]

jira2cli-0.1.0/src/jira2cli/commands/links.py

@@ -0,0 +1,95 @@
+"""Link-management jira2cli commands."""
+
+from __future__ import annotations
+
+import typer
+from jira2ai_core import client
+from jira2ai_core.operations import links
+
+from jira2cli.output import (
+    raise_cli_exception,
+    render_operation_result,
+    validate_output_options,
+)
+
+
+def add_link_command(
+    link_type: str = typer.Argument(..., help="Link type name (e.g. Blocks, Clones)"),
+    outward_key: str = typer.Argument(..., help="Issue key on the outward side."),
+    inward_key: str = typer.Argument(..., help="Issue key on the inward side."),
+    raw_output: bool = typer.Option(
+        False,
+        "--raw",
+        help="Render the raw API payload as JSON.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Render structured output as JSON.",
+    ),
+) -> None:
+    """Create a link between two Jira issues."""
+    validate_output_options(json_output=json_output, raw_output=raw_output)
+
+    try:
+        api = client.get_api()
+        result = links.create_issue_link(
+            link_type,
+            outward_key,
+            inward_key,
+            api=api,
+        )
+    except Exception as exc:
+        raise_cli_exception(exc)
+
+    typer.echo(
+        render_operation_result(
+            result,
+            json_output=json_output,
+            raw_output=raw_output,
+        )
+    )
+
+
+def delete_link_command(
+    link_id: str = typer.Argument(..., help="Issue link ID to delete."),
+    raw_output: bool = typer.Option(
+        False,
+        "--raw",
+        help="Render the raw API payload as JSON.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Render structured output as JSON.",
+    ),
+) -> None:
+    """Delete a Jira issue link by ID."""
+    validate_output_options(json_output=json_output, raw_output=raw_output)
+
+    try:
+        api = client.get_api()
+        result = links.delete_issue_link(link_id, api=api)
+    except Exception as exc:
+        raise_cli_exception(exc)
+
+    typer.echo(
+        render_operation_result(
+            result,
+            json_output=json_output,
+            raw_output=raw_output,
+        )
+    )
+
+
+def register_link_commands(app: typer.Typer) -> None:
+    """Register link-management commands."""
+    app.command("add-link")(add_link_command)
+    app.command("delete-link")(delete_link_command)
+
+
+__all__ = [
+    "add_link_command",
+    "delete_link_command",
+    "register_link_commands",
+]

jira2cli-0.1.0/src/jira2cli/commands/metadata.py

@@ -0,0 +1,205 @@
+"""Metadata and reference jira2cli commands."""
+
+from __future__ import annotations
+
+import typer
+from jira2ai_core import client
+from jira2ai_core.errors import Jira2AIValidationError
+from jira2ai_core.jql import JQL_REFERENCE
+from jira2ai_core.operations import fields as field_operations
+from jira2ai_core.operations import links, projects, users
+
+from jira2cli.output import (
+    raise_cli_exception,
+    render_operation_result,
+    validate_output_options,
+)
+
+
+def fields_command(
+    project_key: str | None = typer.Option(
+        None,
+        "--project-key",
+        help="Project key for issue type or create-field metadata.",
+    ),
+    issue_type: str | None = typer.Option(
+        None,
+        "--issue-type",
+        help="Issue type name used with --project-key for create fields.",
+    ),
+    issue_key: str | None = typer.Option(
+        None,
+        "--issue-key",
+        help="Existing issue key for edit-field metadata.",
+    ),
+    raw_output: bool = typer.Option(
+        False,
+        "--raw",
+        help="Render the raw API payload as JSON.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Render structured output as JSON.",
+    ),
+) -> None:
+    """Get field metadata for creating or editing Jira issues."""
+    validate_output_options(json_output=json_output, raw_output=raw_output)
+
+    try:
+        if issue_key:
+            api = client.get_api()
+            result = field_operations.get_edit_fields(issue_key, api=api)
+        else:
+            if not project_key:
+                raise Jira2AIValidationError(
+                    "Provide either --project-key (to list issue types / create fields) "
+                    "or --issue-key (to list edit fields)."
+                )
+
+            api = client.get_api()
+            if issue_type:
+                result = field_operations.get_create_fields(
+                    project_key,
+                    issue_type,
+                    api=api,
+                )
+            else:
+                result = field_operations.list_issue_types(project_key, api=api)
+    except Exception as exc:
+        raise_cli_exception(exc)
+
+    typer.echo(
+        render_operation_result(
+            result,
+            json_output=json_output,
+            raw_output=raw_output,
+        )
+    )
+
+
+def projects_command(
+    query: str | None = typer.Option(
+        None,
+        "--query",
+        help="Filter by project key or name.",
+    ),
+    raw_output: bool = typer.Option(
+        False,
+        "--raw",
+        help="Render the raw API payload as JSON.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Render structured output as JSON.",
+    ),
+) -> None:
+    """List Jira projects accessible to the current user."""
+    validate_output_options(json_output=json_output, raw_output=raw_output)
+
+    try:
+        api = client.get_api()
+        result = projects.list_projects(query, api=api)
+    except Exception as exc:
+        raise_cli_exception(exc)
+
+    typer.echo(
+        render_operation_result(
+            result,
+            json_output=json_output,
+            raw_output=raw_output,
+        )
+    )
+
+
+def users_command(
+    query: str = typer.Argument(..., help="Search string for user name or email"),
+    max_results: int = typer.Option(
+        10,
+        "--max-results",
+        min=1,
+        max=50,
+        help="Maximum users to return.",
+    ),
+    raw_output: bool = typer.Option(
+        False,
+        "--raw",
+        help="Render the raw API payload as JSON.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Render structured output as JSON.",
+    ),
+) -> None:
+    """Search Jira users by name or email."""
+    validate_output_options(json_output=json_output, raw_output=raw_output)
+
+    try:
+        api = client.get_api()
+        result = users.search_users(query, max_results=max_results, api=api)
+    except Exception as exc:
+        raise_cli_exception(exc)
+
+    typer.echo(
+        render_operation_result(
+            result,
+            json_output=json_output,
+            raw_output=raw_output,
+        )
+    )
+
+
+def link_types_command(
+    raw_output: bool = typer.Option(
+        False,
+        "--raw",
+        help="Render the raw API payload as JSON.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Render structured output as JSON.",
+    ),
+) -> None:
+    """List available Jira issue link types."""
+    validate_output_options(json_output=json_output, raw_output=raw_output)
+
+    try:
+        api = client.get_api()
+        result = links.list_link_types(api=api)
+    except Exception as exc:
+        raise_cli_exception(exc)
+
+    typer.echo(
+        render_operation_result(
+            result,
+            json_output=json_output,
+            raw_output=raw_output,
+        )
+    )
+
+
+def jql_syntax_command() -> None:
+    """Print the shared JQL syntax reference."""
+    typer.echo(JQL_REFERENCE)
+
+
+def register_metadata_commands(app: typer.Typer) -> None:
+    """Register metadata and reference commands."""
+    app.command("fields")(fields_command)
+    app.command("projects")(projects_command)
+    app.command("users")(users_command)
+    app.command("link-types")(link_types_command)
+    app.command("jql-syntax")(jql_syntax_command)
+
+
+__all__ = [
+    "fields_command",
+    "jql_syntax_command",
+    "link_types_command",
+    "projects_command",
+    "register_metadata_commands",
+    "users_command",
+]

jira2cli-0.1.0/src/jira2cli/commands/read.py

@@ -0,0 +1,118 @@
+"""Read-oriented jira2cli commands."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+import typer
+from jira2ai_core import client
+from jira2ai_core.operations import comments, issues
+
+from jira2cli.output import (
+    raise_cli_exception,
+    render_operation_result,
+    validate_output_options,
+)
+
+
+def read_command(
+    issue_key: str = typer.Argument(..., help="Issue key (e.g. PROJ-123)"),
+    extra_fields: list[str] | None = typer.Option(
+        None,
+        "--extra-field",
+        help=(
+            "Additional fields to retrieve beyond the standard read fields. "
+            "May be repeated."
+        ),
+    ),
+    raw_output: bool = typer.Option(
+        False,
+        "--raw",
+        help="Render the raw API payload as JSON.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Render structured output as JSON.",
+    ),
+) -> None:
+    """Read a Jira issue by key with full details."""
+    validate_output_options(json_output=json_output, raw_output=raw_output)
+
+    try:
+        api = client.get_api()
+        result = issues.read_issue(issue_key, extra_fields=extra_fields, api=api)
+    except Exception as exc:
+        raise_cli_exception(exc)
+
+    typer.echo(
+        render_operation_result(
+            result,
+            json_output=json_output,
+            raw_output=raw_output,
+        )
+    )
+
+
+def comments_command(
+    issue_key: str = typer.Argument(..., help="Issue key (e.g. PROJ-123)"),
+    start_at: int = typer.Option(
+        0,
+        "--start-at",
+        min=0,
+        help="Index of the first comment to return.",
+    ),
+    max_results: int = typer.Option(
+        50,
+        "--max-results",
+        min=1,
+        max=100,
+        help="Maximum comments to return.",
+    ),
+    order_by: Literal["created", "-created"] = typer.Option(
+        "created",
+        "--order-by",
+        help="Use created for oldest first or -created for newest first.",
+    ),
+    raw_output: bool = typer.Option(
+        False,
+        "--raw",
+        help="Render the raw API payload as JSON.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Render structured output as JSON.",
+    ),
+) -> None:
+    """List comments on a Jira issue."""
+    validate_output_options(json_output=json_output, raw_output=raw_output)
+
+    try:
+        api = client.get_api()
+        result = comments.list_comments(
+            issue_key,
+            start_at=start_at,
+            max_results=max_results,
+            order_by=order_by,
+            api=api,
+        )
+    except Exception as exc:
+        raise_cli_exception(exc)
+
+    typer.echo(
+        render_operation_result(
+            result,
+            json_output=json_output,
+            raw_output=raw_output,
+        )
+    )
+
+
+def register_read_commands(app: typer.Typer) -> None:
+    """Register read-oriented commands."""
+    app.command("read")(read_command)
+    app.command("comments")(comments_command)
+
+
+__all__ = ["comments_command", "read_command", "register_read_commands"]

jira2cli-0.1.0/src/jira2cli/commands/search.py

@@ -0,0 +1,69 @@
+"""Search jira2cli commands."""
+
+from __future__ import annotations
+
+import typer
+from jira2ai_core import client
+from jira2ai_core.operations import search as search_operations
+
+from jira2cli.output import (
+    raise_cli_exception,
+    render_operation_result,
+    validate_output_options,
+)
+
+
+def search_command(
+    jql: str = typer.Argument(..., help="JQL query string"),
+    max_results: int = typer.Option(
+        20,
+        "--max-results",
+        min=1,
+        max=50,
+        help="Maximum issues to return.",
+    ),
+    fields: list[str] | None = typer.Option(
+        None,
+        "--field",
+        help="Field to include in the search response. May be repeated.",
+    ),
+    raw_output: bool = typer.Option(
+        False,
+        "--raw",
+        help="Render the raw API payload as JSON.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Render structured output as JSON.",
+    ),
+) -> None:
+    """Search Jira issues using JQL."""
+    validate_output_options(json_output=json_output, raw_output=raw_output)
+
+    try:
+        api = client.get_api()
+        result = search_operations.search_issues(
+            jql,
+            max_results=max_results,
+            fields=fields,
+            api=api,
+        )
+    except Exception as exc:
+        raise_cli_exception(exc)
+
+    typer.echo(
+        render_operation_result(
+            result,
+            json_output=json_output,
+            raw_output=raw_output,
+        )
+    )
+
+
+def register_search_commands(app: typer.Typer) -> None:
+    """Register search commands."""
+    app.command("search")(search_command)
+
+
+__all__ = ["register_search_commands", "search_command"]

jira2cli-0.1.0/src/jira2cli/commands/write.py

@@ -0,0 +1,168 @@
+"""Write-oriented jira2cli commands."""
+
+from __future__ import annotations
+
+import typer
+from jira2ai_core import client
+from jira2ai_core.operations import comments as comment_operations
+from jira2ai_core.operations import issues
+
+from jira2cli.output import (
+    raise_cli_exception,
+    render_operation_result,
+    validate_output_options,
+)
+from jira2cli.parsing import parse_fields_json
+
+
+def create_command(
+    project_key: str = typer.Argument(..., help="Project key (e.g. PROJ)"),
+    issue_type: str = typer.Argument(..., help="Issue type name (e.g. Bug, Task)"),
+    summary: str = typer.Argument(..., help="Issue title / summary"),
+    description: str | None = typer.Option(
+        None,
+        "--description",
+        help="Issue description in markdown.",
+    ),
+    fields_json: str | None = typer.Option(
+        None,
+        "--fields-json",
+        help="Additional issue fields as a JSON object.",
+    ),
+    raw_output: bool = typer.Option(
+        False,
+        "--raw",
+        help="Render the raw API payload as JSON.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Render structured output as JSON.",
+    ),
+) -> None:
+    """Create a Jira issue."""
+    fields = parse_fields_json(fields_json)
+    validate_output_options(json_output=json_output, raw_output=raw_output)
+
+    try:
+        api = client.get_api()
+        result = issues.create_issue(
+            project_key,
+            issue_type,
+            summary,
+            description=description,
+            fields=fields,
+            api=api,
+        )
+    except Exception as exc:
+        raise_cli_exception(exc)
+
+    typer.echo(
+        render_operation_result(
+            result,
+            json_output=json_output,
+            raw_output=raw_output,
+        )
+    )
+
+
+def edit_command(
+    issue_key: str = typer.Argument(..., help="Issue key (e.g. PROJ-123)"),
+    summary: str | None = typer.Option(
+        None,
+        "--summary",
+        help="New issue title / summary.",
+    ),
+    description: str | None = typer.Option(
+        None,
+        "--description",
+        help="New issue description in markdown.",
+    ),
+    fields_json: str | None = typer.Option(
+        None,
+        "--fields-json",
+        help="Additional fields to update as a JSON object.",
+    ),
+    raw_output: bool = typer.Option(
+        False,
+        "--raw",
+        help="Render the raw API payload as JSON.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Render structured output as JSON.",
+    ),
+) -> None:
+    """Update a Jira issue."""
+    fields = parse_fields_json(fields_json)
+    validate_output_options(json_output=json_output, raw_output=raw_output)
+    raw = raw_output or json_output
+
+    try:
+        api = client.get_api()
+        result = issues.edit_issue(
+            issue_key,
+            summary=summary,
+            description=description,
+            fields=fields,
+            raw=raw,
+            api=api,
+        )
+    except Exception as exc:
+        raise_cli_exception(exc)
+
+    typer.echo(
+        render_operation_result(
+            result,
+            json_output=json_output,
+            raw_output=raw_output,
+        )
+    )
+
+
+def comment_command(
+    issue_key: str = typer.Argument(..., help="Issue key (e.g. PROJ-123)"),
+    body: str = typer.Argument(..., help="Comment text in markdown"),
+    raw_output: bool = typer.Option(
+        False,
+        "--raw",
+        help="Render the raw API payload as JSON.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Render structured output as JSON.",
+    ),
+) -> None:
+    """Add a comment to a Jira issue."""
+    validate_output_options(json_output=json_output, raw_output=raw_output)
+
+    try:
+        api = client.get_api()
+        result = comment_operations.add_comment(issue_key, body, api=api)
+    except Exception as exc:
+        raise_cli_exception(exc)
+
+    typer.echo(
+        render_operation_result(
+            result,
+            json_output=json_output,
+            raw_output=raw_output,
+        )
+    )
+
+
+def register_write_commands(app: typer.Typer) -> None:
+    """Register write-oriented commands."""
+    app.command("create")(create_command)
+    app.command("edit")(edit_command)
+    app.command("comment")(comment_command)
+
+
+__all__ = [
+    "comment_command",
+    "create_command",
+    "edit_command",
+    "register_write_commands",
+]

jira2cli-0.1.0/src/jira2cli/output.py

@@ -0,0 +1,107 @@
+"""CLI rendering and error helpers for jira2cli."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, NoReturn
+
+import typer
+from jira2ai_core.errors import Jira2AIError, Jira2AIValidationError
+from jira2ai_core.results import OperationResult
+
+
+def render_operation_result(
+    result: OperationResult,
+    *,
+    json_output: bool = False,
+    raw_output: bool = False,
+) -> str:
+    """Render an operation result for CLI stdout."""
+    if json_output or raw_output:
+        return json.dumps(
+            _json_payload(result),
+            indent=2,
+            sort_keys=True,
+            default=str,
+        )
+    return result.text
+
+
+def _json_payload(result: OperationResult) -> Any:
+    """Select the most structured payload available for JSON output."""
+    if result.data is not None:
+        return result.data
+
+    if result.raw_content is None:
+        return result.text
+
+    try:
+        return json.loads(result.raw_content)
+    except json.JSONDecodeError:
+        return result.raw_content
+
+
+def format_cli_error(error: Jira2AIError) -> str:
+    """Format a core error for CLI stderr."""
+    if not error.details:
+        return error.message
+
+    return (
+        f"{error.message}\n"
+        f"Details:\n{json.dumps(error.details, indent=2, sort_keys=True, default=str)}"
+    )
+
+
+def error_exit_code(error: Jira2AIError) -> int:
+    """Return the CLI exit code for a core error."""
+    if isinstance(error, Jira2AIValidationError):
+        return 2
+    return 1
+
+
+def raise_cli_usage_error(
+    message: str,
+    *,
+    param_hint: str | None = None,
+) -> NoReturn:
+    """Write a CLI usage error to stderr and exit with code 2."""
+    if param_hint:
+        typer.echo(f"{param_hint}: {message}", err=True)
+    else:
+        typer.echo(message, err=True)
+    raise typer.Exit(code=2)
+
+
+def validate_output_options(*, json_output: bool, raw_output: bool) -> None:
+    """Reject conflicting structured output flags."""
+    if json_output and raw_output:
+        raise_cli_usage_error(
+            "Use only one of --json or --raw.",
+            param_hint="--json / --raw",
+        )
+
+
+def raise_cli_error(error: Jira2AIError) -> NoReturn:
+    """Write a CLI-friendly core error message to stderr and exit."""
+    typer.echo(format_cli_error(error), err=True)
+    raise typer.Exit(code=error_exit_code(error))
+
+
+def raise_cli_exception(error: Exception) -> NoReturn:
+    """Write a CLI-friendly error message to stderr and exit."""
+    if isinstance(error, Jira2AIError):
+        raise_cli_error(error)
+
+    typer.echo(str(error), err=True)
+    raise typer.Exit(code=1)
+
+
+__all__ = [
+    "error_exit_code",
+    "format_cli_error",
+    "raise_cli_error",
+    "raise_cli_exception",
+    "raise_cli_usage_error",
+    "render_operation_result",
+    "validate_output_options",
+]

jira2cli-0.1.0/src/jira2cli/parsing.py

@@ -0,0 +1,39 @@
+"""Parsing helpers for jira2cli options and arguments."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from jira2cli.output import raise_cli_usage_error
+
+
+def parse_json_object(
+    value: str | None,
+    *,
+    option_name: str,
+) -> dict[str, Any] | None:
+    """Parse an optional JSON object string into a dictionary."""
+    if value is None:
+        return None
+
+    try:
+        parsed = json.loads(value)
+    except json.JSONDecodeError as exc:
+        raise_cli_usage_error(
+            f"must be valid JSON ({exc.msg} at line {exc.lineno}, column {exc.colno})",
+            param_hint=option_name,
+        )
+
+    if not isinstance(parsed, dict):
+        raise_cli_usage_error("must be a JSON object", param_hint=option_name)
+
+    return parsed
+
+
+def parse_fields_json(value: str | None) -> dict[str, Any] | None:
+    """Parse the ``--fields-json`` option into a dictionary."""
+    return parse_json_object(value, option_name="--fields-json")
+
+
+__all__ = ["parse_fields_json", "parse_json_object"]