pal-found-cli 0.1.2__py3-none-any.whl

pal_found_cli/common/metadata-allow-list.md

@@ -0,0 +1,169 @@
+# Core metadata-only allow-list
+
+This packaged policy covers namespaces that share `AccessControlGuard`'s
+default allow-list. Namespace packages with their own policy file pass that
+path explicitly.
+
+| SDK operation | Decision | Notes |
+| --- | --- | --- |
+| `admin.authentication_provider.get` | PERMITTED | |
+| `admin.authentication_provider.list` | PERMITTED | |
+| `admin.cbac_banner.get` | PERMITTED | |
+| `admin.cbac_marking_restrictions.get` | PERMITTED | |
+| `admin.enrollment.get` | PERMITTED | |
+| `admin.enrollment.get_current` | PERMITTED | |
+| `admin.enrollment_role_assignment.list` | PERMITTED | |
+| `admin.group.get` | PERMITTED | |
+| `admin.group.get_batch` | PERMITTED | |
+| `admin.group.list` | PERMITTED | |
+| `admin.group.list_current` | PERMITTED | |
+| `admin.group.search` | PERMITTED | |
+| `admin.group_member.list` | PERMITTED | |
+| `admin.group_membership.list` | PERMITTED | |
+| `admin.group_membership_expiration_policy.get` | PERMITTED | |
+| `admin.group_provider_info.get` | PERMITTED | |
+| `admin.host.list` | PERMITTED | |
+| `admin.marking.get` | PERMITTED | |
+| `admin.marking.get_batch` | PERMITTED | |
+| `admin.marking.list` | PERMITTED | |
+| `admin.marking_category.get` | PERMITTED | |
+| `admin.marking_category.list` | PERMITTED | |
+| `admin.marking_member.list` | PERMITTED | |
+| `admin.marking_role_assignment.list` | PERMITTED | |
+| `admin.organization.get` | PERMITTED | |
+| `admin.organization.list_available_roles` | PERMITTED | |
+| `admin.organization_guest_member.list` | PERMITTED | |
+| `admin.organization_role_assignment.list` | PERMITTED | |
+| `admin.role.get` | PERMITTED | |
+| `admin.role.get_batch` | PERMITTED | |
+| `admin.user.get` | PERMITTED | |
+| `admin.user.get_batch` | PERMITTED | |
+| `admin.user.get_current` | PERMITTED | |
+| `admin.user.get_markings` | PERMITTED | |
+| `admin.user.list` | PERMITTED | |
+| `admin.user.search` | PERMITTED | |
+| `admin.user_provider_info.get` | PERMITTED | |
+| `datasets.branch.get` | PERMITTED | |
+| `datasets.branch.list` | PERMITTED | |
+| `datasets.branch.transactions` | PERMITTED | |
+| `datasets.dataset.get` | PERMITTED | |
+| `datasets.dataset.get_health_check_reports` | PERMITTED | |
+| `datasets.dataset.get_health_checks` | PERMITTED | |
+| `datasets.dataset.get_schedules` | PERMITTED | |
+| `datasets.dataset.get_schema` | PERMITTED | |
+| `datasets.dataset.get_schema_batch` | PERMITTED | |
+| `datasets.dataset.jobs` | PERMITTED | |
+| `datasets.dataset.transactions` | PERMITTED | |
+| `datasets.file.get` | PERMITTED | |
+| `datasets.file.list` | PERMITTED | |
+| `datasets.transaction.get` | PERMITTED | |
+| `datasets.transaction.job` | PERMITTED | |
+| `datasets.view.get` | PERMITTED | |
+| `filesystem.folder.children` | PERMITTED | |
+| `filesystem.folder.get` | PERMITTED | |
+| `filesystem.folder.get_batch` | PERMITTED | |
+| `filesystem.project.get` | PERMITTED | |
+| `filesystem.project.organizations` | PERMITTED | |
+| `filesystem.resource.get` | PERMITTED | |
+| `filesystem.resource.get_access_requirements` | PERMITTED | |
+| `filesystem.resource.get_batch` | PERMITTED | |
+| `filesystem.resource.get_by_path` | PERMITTED | |
+| `filesystem.resource.get_by_path_batch` | PERMITTED | |
+| `filesystem.resource.markings` | PERMITTED | |
+| `filesystem.resource_role.list` | PERMITTED | |
+| `filesystem.space.get` | PERMITTED | |
+| `filesystem.space.list` | PERMITTED | |
+| `functions.query.get` | PERMITTED | |
+| `functions.query.get_by_rid` | PERMITTED | |
+| `functions.query.get_by_rid_batch` | PERMITTED | |
+| `functions.value_type.get` | PERMITTED | |
+| `functions.version_id.get` | PERMITTED | |
+| `ontologies.action_type.get` | PERMITTED | |
+| `ontologies.action_type.get_by_rid` | PERMITTED | |
+| `ontologies.action_type.get_by_rid_batch` | PERMITTED | |
+| `ontologies.action_type.list` | PERMITTED | |
+| `ontologies.action_type_full_metadata.get` | PERMITTED | |
+| `ontologies.action_type_full_metadata.list` | PERMITTED | |
+| `ontologies.attachment.get` | PERMITTED | |
+| `ontologies.attachment_property.get_attachment` | PERMITTED | |
+| `ontologies.attachment_property.get_attachment_by_rid` | PERMITTED | |
+| `ontologies.media_reference_property.get_media_metadata` | PERMITTED | |
+| `ontologies.object_type.get` | PERMITTED | |
+| `ontologies.object_type.get_by_rid_batch` | PERMITTED | |
+| `ontologies.object_type.get_full_metadata` | PERMITTED | |
+| `ontologies.object_type.get_outgoing_link_type` | PERMITTED | |
+| `ontologies.object_type.list` | PERMITTED | |
+| `ontologies.object_type.list_outgoing_link_types` | PERMITTED | |
+| `ontologies.ontology.get` | PERMITTED | |
+| `ontologies.ontology.get_full_metadata` | PERMITTED | |
+| `ontologies.ontology.list` | PERMITTED | |
+| `ontologies.ontology.load_metadata` | PERMITTED | |
+| `ontologies.ontology_interface.get` | PERMITTED | |
+| `ontologies.ontology_interface.get_outgoing_interface_link_type` | PERMITTED | |
+| `ontologies.ontology_interface.list` | PERMITTED | |
+| `ontologies.ontology_interface.list_outgoing_interface_link_types` | PERMITTED | |
+| `ontologies.ontology_value_type.get` | PERMITTED | |
+| `ontologies.ontology_value_type.list` | PERMITTED | |
+| `ontologies.query_type.get` | PERMITTED | |
+| `ontologies.query_type.list` | PERMITTED | |
+| `aip_agents.agent.get` | PERMITTED | |
+| `aip_agents.agent_version.get` | PERMITTED | |
+| `aip_agents.agent_version.list` | PERMITTED | |
+| `aip_agents.session.get` | PERMITTED | |
+| `aip_agents.session.list` | PERMITTED | |
+| `aip_agents.session_trace.get` | PERMITTED | |
+| `audit.log_file.list` | PERMITTED | |
+| `checkpoints.record.get` | PERMITTED | |
+| `checkpoints.record.get_batch` | PERMITTED | |
+| `checkpoints.record.search` | PERMITTED | |
+| `connectivity.connection.get` | PERMITTED | |
+| `connectivity.connection.get_configuration` | PERMITTED | |
+| `connectivity.connection.get_configuration_batch` | PERMITTED | |
+| `connectivity.file_import.get` | PERMITTED | |
+| `connectivity.file_import.list` | PERMITTED | |
+| `connectivity.table_import.get` | PERMITTED | |
+| `connectivity.table_import.list` | PERMITTED | |
+| `data_health.check.get` | PERMITTED | |
+| `data_health.check_report.get` | PERMITTED | |
+| `data_health.check_report.get_latest` | PERMITTED | |
+| `media_sets.media_set.get` | PERMITTED | |
+| `media_sets.media_set.get_rid_by_path` | PERMITTED | |
+| `media_sets.media_set.get_status` | PERMITTED | |
+| `media_sets.media_set.info` | PERMITTED | |
+| `media_sets.media_set.metadata` | PERMITTED | |
+| `models.experiment.get` | PERMITTED | |
+| `models.experiment.search` | PERMITTED | |
+| `models.model.get` | PERMITTED | |
+| `models.model_studio.get` | PERMITTED | |
+| `models.model_studio_config_version.get` | PERMITTED | |
+| `models.model_studio_config_version.latest` | PERMITTED | |
+| `models.model_studio_config_version.list` | PERMITTED | |
+| `models.model_studio_run.list` | PERMITTED | |
+| `models.model_studio_trainer.get` | PERMITTED | |
+| `models.model_studio_trainer.list` | PERMITTED | |
+| `models.model_version.get` | PERMITTED | |
+| `models.model_version.list` | PERMITTED | |
+| `orchestration.build.get` | PERMITTED | |
+| `orchestration.build.get_batch` | PERMITTED | |
+| `orchestration.build.jobs` | PERMITTED | |
+| `orchestration.build.search` | PERMITTED | |
+| `orchestration.job.get` | PERMITTED | |
+| `orchestration.job.get_batch` | PERMITTED | |
+| `orchestration.schedule.get` | PERMITTED | |
+| `orchestration.schedule.get_affected_resources` | PERMITTED | |
+| `orchestration.schedule.get_batch` | PERMITTED | |
+| `orchestration.schedule.runs` | PERMITTED | |
+| `orchestration.schedule_version.get` | PERMITTED | |
+| `orchestration.schedule_version.schedule` | PERMITTED | |
+| `sql_queries.sql_query.get_status` | PERMITTED | |
+| `streams.stream.get` | PERMITTED | |
+| `streams.stream.get_end_offsets` | PERMITTED | |
+| `streams.subscriber.get_read_position` | PERMITTED | |
+| `third_party_applications.third_party_application.get` | PERMITTED | |
+| `third_party_applications.version.get` | PERMITTED | |
+| `third_party_applications.version.list` | PERMITTED | |
+| `third_party_applications.website.get` | PERMITTED | |
+| `widgets.release.get` | PERMITTED | |
+| `widgets.release.list` | PERMITTED | |
+| `widgets.repository.get` | PERMITTED | |
+| `widgets.widget_set.get` | PERMITTED | |

pal_found_cli/common/output_formatter.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+"""OutputFormatter with auto-selection (ADR-004).
+
+Implements the format auto-selection algorithm defined in ADR-004.
+Supports JSON and TOON output formats with intelligent format selection
+based on data shape and user configuration.
+
+Format Selection Algorithm (ADR-004)
+------------------------------------
+1. Explicit format always wins
+2. Errors always use JSON
+3. Non-list top-level always uses JSON
+4. Empty list uses JSON
+5. Extract field sets from all items
+6. Any non-dict item → JSON
+7. All items must share identical field set → TOON, else JSON
+"""
+
+import json
+import os
+import sys
+from typing import Any
+
+# Environment variable for default format
+ENV_DEFAULT_FORMAT = "FOUNDRY_AGENTIC_CLI_DEFAULT_FORMAT"
+
+
+class OutputFormatter:
+    """Formats output data as JSON or TOON with auto-selection (ADR-004).
+
+    Implements the 7-step auto-selection algorithm from ADR-004.
+    Supports explicit format override and pretty-printing.
+
+    Parameters
+    ----------
+    format_setting : str, optional
+        Format setting: 'json', 'toon', or 'auto'. Defaults to env var
+        `FOUNDRY_AGENTIC_CLI_DEFAULT_FORMAT`, then to 'auto'.
+    pretty : bool, optional
+        Enable pretty-printing for JSON output. Default: False.
+
+    Examples
+    --------
+    >>> formatter = OutputFormatter(format_setting="auto")
+    >>> output = formatter.format(data)
+    >>> print(output)
+    """
+
+    def __init__(
+        self,
+        format_setting: str | None = None,
+        pretty: bool = False,
+    ) -> None:
+        self.format_setting = format_setting or os.environ.get(
+            ENV_DEFAULT_FORMAT, "auto"
+        )
+        self.pretty = pretty
+
+    def _select_format(self, data: Any) -> str:
+        """Apply ADR-004 format auto-selection algorithm.
+
+        Algorithm:
+        1. Explicit format always wins
+        2. Errors always use JSON
+        3. Non-list top-level always uses JSON
+        4. Empty list uses JSON
+        5. Extract field sets from all items
+        6. Any non-dict item → JSON
+        7. All items must share identical field set → TOON, else JSON
+
+        Parameters
+        ----------
+        data : Any
+            The data to format.
+
+        Returns
+        -------
+        str
+            Selected format: 'json' or 'toon'.
+        """
+        # 1. Explicit format always wins
+        if self.format_setting in ("json", "toon"):
+            return self.format_setting
+
+        # 2. Errors always use JSON
+        if isinstance(data, dict) and data.get("error"):
+            return "json"
+
+        # 3. Non-list top-level always uses JSON
+        if not isinstance(data, list):
+            return "json"
+
+        # 4. Empty list uses JSON
+        if len(data) == 0:
+            return "json"
+
+        # 5. Extract field sets from all items
+        field_sets = []
+        for item in data:
+            if isinstance(item, dict):
+                field_sets.append(frozenset(item.keys()))
+
+        # 6. Any non-dict item → JSON
+        if len(field_sets) != len(data):
+            return "json"
+
+        # 7. All items must share identical field set → TOON, else JSON
+        if len(set(field_sets)) == 1:
+            return "toon"
+
+        return "json"
+
+    def _format_json(self, data: Any) -> str:
+        """Format data as JSON.
+
+        Parameters
+        ----------
+        data : Any
+            Data to serialize as JSON.
+
+        Returns
+        -------
+        str
+            JSON string.
+        """
+        if self.pretty:
+            return json.dumps(data, indent=2, default=str)
+        return json.dumps(data, default=str)
+
+    def _format_toon(self, data: list[dict[str, Any]]) -> str:
+        """Format data as TOON (tabular output).
+
+        TOON format: human-readable table/line format.
+        Each dict item becomes a row with aligned columns.
+
+        Parameters
+        ----------
+        data : List[Dict[str, Any]]
+            List of uniform dicts to format as table.
+
+        Returns
+        -------
+        str
+            TOON-formatted string.
+        """
+        if not data:
+            return ""
+
+        # Extract headers (keys from first item)
+        headers = list(data[0].keys())
+
+        # Calculate column widths
+        col_widths = {h: len(str(h)) for h in headers}
+        for row in data:
+            for h in headers:
+                val_len = len(str(row.get(h, "")))
+                col_widths[h] = max(col_widths[h], val_len)
+
+        # Build table
+        lines = []
+
+        # Header line
+        header_line = "  ".join(str(h).ljust(col_widths[h]) for h in headers)
+        lines.append(header_line)
+
+        # Separator
+        separator = "  ".join("-" * col_widths[h] for h in headers)
+        lines.append(separator)
+
+        # Data rows
+        for row in data:
+            row_line = "  ".join(
+                str(row.get(h, "")).ljust(col_widths[h]) for h in headers
+            )
+            lines.append(row_line)
+
+        return "\n".join(lines)
+
+    def format(self, data: Any) -> str:
+        """Format data according to format setting and ADR-004 algorithm.
+
+        Parameters
+        ----------
+        data : Any
+            Data to format. Can be dict, list, or scalar.
+
+        Returns
+        -------
+        str
+            Formatted string output.
+
+        Raises
+        ------
+        ValueError
+            If format_setting is not one of 'json', 'toon', 'auto'.
+        """
+        if self.format_setting not in ("json", "toon", "auto"):
+            raise ValueError(
+                f"Invalid format_setting '{self.format_setting}'. "
+                f"Must be one of: 'json', 'toon', 'auto'"
+            )
+
+        selected_format = self._select_format(data)
+
+        if selected_format == "toon":
+            if isinstance(data, list) and data and isinstance(data[0], dict):
+                return self._format_toon(data)
+            # Fallback to JSON if TOON not applicable
+            return self._format_json(data)
+
+        return self._format_json(data)
+
+    def format_error(self, error_data: dict[str, Any]) -> str:
+        """Format error data (always JSON per ADR-004).
+
+        Parameters
+        ----------
+        error_data : Dict[str, Any]
+            Error envelope dictionary.
+
+        Returns
+        -------
+        str
+            JSON-formatted error string.
+        """
+        return self._format_json(error_data)
+
+    def emit(self, data: Any) -> None:
+        """Format and emit data to stdout.
+
+        Parameters
+        ----------
+        data : Any
+            Data to format and emit.
+        """
+        output = self.format(data)
+        sys.stdout.write(output + "\n")
+        sys.stdout.flush()
+
+    def emit_error(self, error_data: dict[str, Any]) -> None:
+        """Format and emit error data to stderr.
+
+        Per ADR-004, error output always goes to stderr (not stdout),
+        keeping the CLI contract of stdout for primary result data only.
+
+        Parameters
+        ----------
+        error_data : Dict[str, Any]
+            Error envelope dictionary.
+        """
+        output = self.format_error(error_data)
+        sys.stderr.write(output + "\n")
+        sys.stderr.flush()
+
+    def emit_to_stderr(self, data: Any) -> None:
+        """Emit data (e.g. pagination metadata) to stderr as JSON.
+
+        Per ADR-004, pagination metadata always goes to stderr as JSON.
+
+        Parameters
+        ----------
+        data : Any
+            Data to emit to stderr.
+        """
+        output = json.dumps(data, default=str)
+        sys.stderr.write(output + "\n")
+        sys.stderr.flush()

pal_found_cli/common/pagination_helper.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""PaginationHelper — manages --page-size, --page-token, --batch-pages (SRS §3.5).
+
+Handles paginated SDK responses and emits metadata to stderr
+with pagination cursors per ADR-005.
+
+Default: return first page only with page_token on stderr.
+Batch mode: agent specifies number of pages (max 40).
+
+Environment variables:
+- FOUNDRY_AGENTIC_CLI_DEFAULT_PAGE_SIZE (default: 100)
+- FOUNDRY_AGENTIC_CLI_MAX_BATCH_PAGES (default: 40)
+"""
+
+import json
+import os
+import sys
+from typing import Any
+
+from pal_found_cli.common.log_setup import METADATA_SEPARATOR
+
+# Default values (from SRS-001 §5)
+DEFAULT_PAGE_SIZE = int(os.environ.get("FOUNDRY_AGENTIC_CLI_DEFAULT_PAGE_SIZE", "100"))
+HARD_MAX_BATCH_PAGES = 40
+MAX_BATCH_PAGES = min(
+    int(
+        os.environ.get("FOUNDRY_AGENTIC_CLI_MAX_BATCH_PAGES", str(HARD_MAX_BATCH_PAGES))
+    ),
+    HARD_MAX_BATCH_PAGES,
+)
+
+
+class PaginationHelper:
+    """Manages pagination for SDK calls.
+
+    Parameters
+    ----------
+    page_size : int or None
+        Number of items per page. Defaults to FOUNDRY_AGENTIC_CLI_DEFAULT_PAGE_SIZE (100).
+    page_token : str or None
+        Resume from this cursor.
+    batch_pages : int or None
+        Number of pages to retrieve (default 1, max FOUNDRY_AGENTIC_CLI_MAX_BATCH_PAGES).
+
+    Usage
+    -----
+    >>> helper = PaginationHelper(page_size=50, page_token=None, batch_pages=1)
+    >>> result = await helper.paginate(client_method, helper)
+    >>> helper.emit_metadata()  # writes to stderr
+    """
+
+    def __init__(
+        self,
+        page_size: int | None = None,
+        page_token: str | None = None,
+        batch_pages: int | None = None,
+    ) -> None:
+        self.page_size = self._validate_positive_int(
+            "page_size",
+            page_size if page_size is not None else DEFAULT_PAGE_SIZE,
+        )
+        self.page_token = page_token
+        raw_batch = self._validate_positive_int(
+            "batch_pages",
+            batch_pages if batch_pages is not None else 1,
+        )
+        self.batch_pages = min(raw_batch, MAX_BATCH_PAGES)
+        self._next_page_token: str | None = None
+        self._total_items: int = 0
+        self._pages_fetched: int = 0
+
+    @staticmethod
+    def _validate_positive_int(name: str, value: int) -> int:
+        """Validate that a pagination argument is a positive integer."""
+        if isinstance(value, bool) or not isinstance(value, int):
+            raise TypeError(f"{name} must be a positive integer")
+        if value <= 0:
+            raise ValueError(f"{name} must be a positive integer")
+        return value
+
+    @property
+    def next_page_token(self) -> str | None:
+        """Cursor for next page."""
+        return self._next_page_token
+
+    @property
+    def total_items(self) -> int:
+        """Total items fetched across all pages."""
+        return self._total_items
+
+    @property
+    def pages_fetched(self) -> int:
+        """Number of pages fetched."""
+        return self._pages_fetched
+
+    def get_sdk_params(self) -> dict[str, Any]:
+        """Get pagination parameters for SDK call.
+
+        Returns
+        -------
+        dict
+            SDK-compatible pagination kwargs.
+        """
+        params: dict[str, Any] = {}
+        if self.page_size is not None:
+            params["page_size"] = self.page_size
+        if self.page_token is not None:
+            params["page_token"] = self.page_token
+        return params
+
+    def _extract_items(self, response: Any) -> list[Any]:
+        """Extract items list from SDK response.
+
+        Parameters
+        ----------
+        response : Any
+            SDK response object.
+
+        Returns
+        -------
+        list
+            List of items from the response.
+        """
+        if isinstance(response, dict):
+            return response.get("items", []) or []
+        if isinstance(response, list):
+            return response
+        if hasattr(response, "items"):
+            return getattr(response, "items", []) or []
+        return [response] if response else []
+
+    def _extract_next_token(self, response: Any) -> str | None:
+        """Extract next page token from SDK response.
+
+        Parameters
+        ----------
+        response : Any
+            SDK response object.
+
+        Returns
+        -------
+        str or None
+            Next page token.
+        """
+        if isinstance(response, dict):
+            return response.get("next_page_token") or response.get("nextPageToken")
+        if hasattr(response, "next_page_token"):
+            return getattr(response, "next_page_token", None)
+        if hasattr(response, "nextPageToken"):
+            return getattr(response, "nextPageToken", None)
+        return None
+
+    async def paginate(
+        self,
+        call_func,
+        **call_kwargs,
+    ) -> list[Any]:
+        """Execute paginated SDK calls.
+
+        Parameters
+        ----------
+        call_func : callable
+            Async SDK method to call.
+        **call_kwargs
+            Additional kwargs to pass to SDK method.
+
+        Returns
+        -------
+        list
+            Aggregated items from all pages.
+        """
+        all_items: list[Any] = []
+        token = self.page_token
+
+        for _ in range(self.batch_pages):
+            # Build params
+            params = dict(call_kwargs)
+            if self.page_size is not None:
+                params["page_size"] = self.page_size
+            if token is not None:
+                params["page_token"] = token
+
+            response = await call_func(**params)
+            items = self._extract_items(response)
+            all_items.extend(items)
+            self._total_items += len(items)
+            self._pages_fetched += 1
+
+            token = self._extract_next_token(response)
+            if token is None:
+                break
+
+        self._next_page_token = token
+        return all_items
+
+    def emit_metadata(self) -> None:
+        """Emit pagination metadata to stderr (ADR-005).
+
+        Writes METADATA_SEPARATOR followed by JSON metadata.
+        """
+        metadata: dict[str, Any] = {
+            "pages_fetched": self._pages_fetched,
+            "total_items": self._total_items,
+        }
+        if self._next_page_token:
+            metadata["next_page_token"] = self._next_page_token
+        if self.page_size:
+            metadata["page_size"] = self.page_size
+
+        sys.stderr.write(METADATA_SEPARATOR + "\n")
+        sys.stderr.write(json.dumps(metadata) + "\n")
+        sys.stderr.flush()