gcpath 0.1.0__py3-none-any.whl

gcpath/cli.py

@@ -0,0 +1,298 @@
+import typer
+import logging
+from typing import Optional, List, Dict
+from typing_extensions import Annotated
+from rich.console import Console
+from rich import print as rprint
+from google.api_core import exceptions as gcp_exceptions
+
+from gcpath.core import Hierarchy, path_escape, Project, GCPathError
+
+app = typer.Typer(
+    name="gcpath",
+    help="Google Cloud Platform resource hierarchy utility",
+    add_completion=False,
+)
+console = Console()
+error_console = Console(stderr=True)
+
+
+def handle_error(e: Exception) -> None:
+    """Central error handler for CLI."""
+    if isinstance(e, GCPathError):
+        error_console.print(f"[red]Error:[/red] {e}")
+    elif isinstance(e, gcp_exceptions.PermissionDenied):
+        error_console.print(
+            "[red]Permission Denied:[/red] Ensure you have the required permissions and are authenticated."
+        )
+        error_console.print("[dim]Hint: Run 'gcloud auth application-default login'[/dim]")
+    elif isinstance(e, gcp_exceptions.ServiceUnavailable):
+        error_console.print("[red]Service Unavailable:[/red] The GCP API is currently unreachable.")
+    elif isinstance(e, Exception):
+        error_console.print(f"[red]Unexpected Error:[/red] {e}")
+        logging.exception("Unexpected error occurred")
+    raise typer.Exit(code=1)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    use_asset_api: bool = typer.Option(
+        True,
+        "--use-asset-api/--no-use-asset-api",
+        "-u/-U",
+        help="Use Cloud Asset API to load folders (faster) or Resource Manager (slower)",
+    ),
+    debug: bool = typer.Option(False, "--debug", help="Enable debug logging"),
+) -> None:
+    """
+    gcpath - Google Cloud Platform resource hierarchy utility
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["use_asset_api"] = use_asset_api
+    
+    if debug:
+        logging.basicConfig(level=logging.DEBUG)
+    else:
+        logging.basicConfig(level=logging.ERROR)
+
+
+@app.command()
+def ls(
+    ctx: typer.Context,
+    organizations: Annotated[
+        Optional[List[str]],
+        typer.Argument(help="Organization display names to filter (optional)"),
+    ] = None,
+    long: bool = typer.Option(
+        False, "--long", "-l", help="Show resource names along with paths"
+    ),
+    recursive: bool = typer.Option(
+        True, "--recursive/--no-recursive", "-R/-r", help="List resources recursively"
+    ),
+) -> None:
+    """
+    List all folders and projects in your organizations.
+    """
+    try:
+        hierarchy = Hierarchy.load(
+            display_names=organizations, 
+            via_resource_manager=not ctx.obj["use_asset_api"]
+        )
+
+        if not hierarchy.organizations and not hierarchy.projects:
+            # Check if it looks like a personal account
+            import google.auth
+
+            account_msg = ""
+            try:
+                credentials, _ = google.auth.default()
+                if hasattr(credentials, "account") and credentials.account:
+                    if credentials.account.endswith("@gmail.com"):
+                        account_msg = f" (Account: {credentials.account})"
+            except Exception:
+                pass
+
+            rprint(
+                f"[yellow]No organizations or projects found accessible to your account{account_msg}.[/yellow]"
+            )
+            if not account_msg:
+                rprint(
+                    "[dim]Hint: You might not have access to any organizations. Projects without organizations are shown with //_ prefix.[/dim]"
+                )
+            return
+
+        items = []
+        for org in hierarchy.organizations:
+            if recursive:
+                # Add org itself
+                items.append(
+                    (
+                        f"//{path_escape(org.organization.display_name)}",
+                        org.organization.name,
+                    )
+                )
+                for folder in org.folders.values():
+                    items.append((folder.path, folder.name))
+            else:
+                # Only top level
+                items.append(
+                    (
+                        f"//{path_escape(org.organization.display_name)}",
+                        org.organization.name,
+                    )
+                )
+
+        for proj in hierarchy.projects:
+            if recursive or not proj.folder:
+                items.append((proj.path, proj.name))
+
+        # Sort items for consistent output
+        items.sort(key=lambda x: x[0])
+
+        for path, res_name in items:
+            if long:
+                print(f"{path:<60} {res_name}")
+            else:
+                print(path)
+
+    except Exception as e:
+        handle_error(e)
+
+
+@app.command()
+def tree(
+    ctx: typer.Context,
+    organizations: Annotated[
+        Optional[List[str]],
+        typer.Argument(help="Organization display names to filter (optional)"),
+    ] = None,
+    level: int = typer.Option(
+        None, "--level", "-L", help="Max display depth of the tree"
+    ),
+    show_ids: bool = typer.Option(
+        False, "--ids", "-i", help="Show resource names in the tree"
+    ),
+) -> None:
+    """
+    Display the resource hierarchy in a tree format.
+    """
+    from rich.tree import Tree
+
+    try:
+        hierarchy = Hierarchy.load(
+            display_names=organizations, 
+            via_resource_manager=not ctx.obj["use_asset_api"]
+        )
+
+        root_tree = Tree("[bold cyan]GCP Hierarchy[/bold cyan]")
+
+        # Group projects by parent
+        projects_by_parent: Dict[str, List[Project]] = {}
+        for proj in hierarchy.projects:
+            projects_by_parent.setdefault(proj.parent, []).append(proj)
+
+        def add_folders(tree_node, org_node, parent_name, current_depth):
+            if level is not None and current_depth > level:
+                return
+
+            subfolders = []
+            for f in org_node.folders.values():
+                if len(f.ancestors) == 1 and parent_name == org_node.organization.name:
+                    subfolders.append(f)
+                elif len(f.ancestors) > 1 and f.ancestors[1] == parent_name:
+                    subfolders.append(f)
+
+            subfolders.sort(key=lambda x: x.display_name)
+
+            for f in subfolders:
+                label = f"[bold blue]{f.display_name}[/bold blue]"
+                if show_ids:
+                    label += f" [dim]({f.name})[/dim]"
+                sub_node = tree_node.add(label)
+
+                # Add projects in this folder
+                add_projects(sub_node, f.name, current_depth + 1)
+
+                # Recurse
+                add_folders(sub_node, org_node, f.name, current_depth + 1)
+
+        def add_projects(tree_node, parent_name, current_depth):
+            if level is not None and current_depth > level:
+                return
+            projs = projects_by_parent.get(parent_name, [])
+            projs.sort(key=lambda x: x.display_name)
+            for p in projs:
+                label = f"[green]{p.display_name}[/green]"
+                if show_ids:
+                    label += f" [dim]({p.name})[/dim]"
+                tree_node.add(label)
+
+        # Add Organizations
+        for org in hierarchy.organizations:
+            label = f"[bold magenta]{org.organization.display_name}[/bold magenta]"
+            if show_ids:
+                label += f" [dim]({org.organization.name})[/dim]"
+            org_tree = root_tree.add(label)
+
+            add_projects(org_tree, org.organization.name, 1)
+            add_folders(org_tree, org, org.organization.name, 1)
+
+        # Add Organizationless projects
+        if any(not p.organization for p in hierarchy.projects):
+            orgless_node = root_tree.add(
+                "[bold yellow](organizationless)[/bold yellow]"
+            )
+            for p in hierarchy.projects:
+                if not p.organization:
+                    label = f"[green]{p.display_name}[/green]"
+                    if show_ids:
+                        label += f" [dim]({p.name})[/dim]"
+                    orgless_node.add(label)
+
+        console.print(root_tree)
+
+    except Exception as e:
+        handle_error(e)
+
+
+@app.command(name="name")
+def get_resource_name(
+    ctx: typer.Context,
+    paths: Annotated[
+        List[str], typer.Argument(help="Paths to resolve, e.g. //example.com/folder")
+    ],
+    id_only: bool = typer.Option(
+        False, "--id", help="Print only the resource ID number"
+    ),
+) -> None:
+    """
+    Get Google Cloud Platform resource name by path.
+    """
+    try:
+        hierarchy = Hierarchy.load(
+            display_names=None, 
+            via_resource_manager=not ctx.obj["use_asset_api"]
+        )
+
+        for path in paths:
+            res_name = hierarchy.get_resource_name(path)
+            if id_only:
+                parts = res_name.split("/")
+                res_name = parts[-1]
+            print(res_name)
+
+    except Exception as e:
+        handle_error(e)
+
+
+@app.command(name="path")
+def get_path_command(
+    ctx: typer.Context,
+    resource_names: Annotated[
+        List[str], typer.Argument(help="Resource names to resolve, e.g. folders/123")
+    ],
+) -> None:
+    """
+    Get path of a resource name.
+    """
+    try:
+        hierarchy = Hierarchy.load(
+            display_names=None, 
+            via_resource_manager=not ctx.obj["use_asset_api"]
+        )
+
+        for name in resource_names:
+            p = hierarchy.get_path_by_resource_name(name)
+            print(p)
+
+    except Exception as e:
+        handle_error(e)
+
+
+def run() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    app()

gcpath/core.py

@@ -0,0 +1,490 @@
+import logging
+import urllib.parse
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+from google.cloud import resourcemanager_v3, asset_v1  # type: ignore
+from google.api_core import exceptions
+
+# We use a logger but don't configure it here.
+# Configuration should happen at the application entry point.
+logger = logging.getLogger(__name__)
+
+
+class GCPathError(Exception):
+    """Base exception for gcpath."""
+    pass
+
+
+class ResourceNotFoundError(GCPathError, ValueError):
+    """Raised when a resource is not found."""
+    pass
+
+
+class PathParsingError(GCPathError, ValueError):
+    """Raised when a path cannot be parsed."""
+    pass
+
+
+def path_escape(display_name: str) -> str:
+    """Escape display names for use in paths."""
+    return urllib.parse.quote(display_name, safe="")
+
+
+def _clean_asset_name(name: str) -> str:
+    """Strips the Asset API prefix from resource names."""
+    prefix = "//cloudresourcemanager.googleapis.com/"
+    if name.startswith(prefix):
+        return name[len(prefix) :]
+    return name
+
+
+@dataclass
+class OrganizationNode:
+    organization: resourcemanager_v3.Organization
+    folders: Dict[str, "Folder"] = field(default_factory=dict)
+
+    def paths(self) -> List[str]:
+        return [f.path for f in self.folders.values()]
+
+    def get_resource_name(self, path: str) -> str:
+        # path e.g. / or /a/b
+        clean_path = path.strip("/")
+        if not clean_path:
+            return self.organization.name
+
+        parts = clean_path.split("/")
+        matches = []
+        for folder in self.folders.values():
+            if folder.is_path_match(parts):
+                matches.append(folder)
+
+        if len(matches) == 0:
+            raise ResourceNotFoundError(
+                f"No folder found with path '{path}' in '{self.organization.display_name}'"
+            )
+        if len(matches) > 1:
+            raise ResourceNotFoundError(
+                f"Multiple folders found with path '{path}' in '{self.organization.display_name}'"
+            )
+
+        return matches[0].name
+
+
+@dataclass
+class Folder:
+    name: str
+    display_name: str
+    ancestors: List[str]
+    organization: "OrganizationNode"
+
+    def is_path_match(self, path_parts: List[str]) -> bool:
+        # path matching logic
+        if len(path_parts) + 1 != len(self.ancestors):
+            return False
+
+        # Determine ancestors to check against path.
+        for i, part in enumerate(path_parts):
+            ancestor_resource_name = self.ancestors[len(path_parts) - i - 1]
+            folder = self.organization.folders.get(ancestor_resource_name)
+            if not folder:
+                return False
+
+            if folder.display_name != part:
+                return False
+
+        return True
+
+    @property
+    def path(self) -> str:
+        # Reconstruct path
+        path_str = "//" + path_escape(self.organization.organization.display_name)
+
+        # We iterate from Top to Bottom: [Leaf, Parent, ..., Org]
+        if len(self.ancestors) >= 2:
+            for i in range(len(self.ancestors) - 2, -1, -1):
+                res_name = self.ancestors[i]
+                parent = self.organization.folders.get(res_name)
+                if parent:
+                    path_str += "/" + path_escape(parent.display_name)
+                else:
+                    logger.warning(f"Ancestor {res_name} not found in folders map")
+        return path_str
+
+
+@dataclass
+class Project:
+    name: str
+    project_id: str
+    display_name: str
+    parent: str
+    organization: Optional["OrganizationNode"]
+    folder: Optional[Folder]
+
+    @property
+    def path(self) -> str:
+        if self.folder:
+            return f"{self.folder.path}/{path_escape(self.display_name)}"
+        if self.organization:
+            return f"//{path_escape(self.organization.organization.display_name)}/{path_escape(self.display_name)}"
+        # Organizationless project
+        return f"//_/{path_escape(self.display_name)}"
+
+
+class Hierarchy:
+    def __init__(self, organizations: List[OrganizationNode], projects: List[Project]):
+        self.organizations = organizations
+        self.projects = projects
+
+        # Build lookup maps for O(1) resource name resolution
+        self._orgs_by_name: Dict[str, OrganizationNode] = {
+            o.organization.name: o for o in organizations
+        }
+        self._folders_by_name: Dict[str, Folder] = {}
+        for org in organizations:
+            self._folders_by_name.update(org.folders)
+
+        # Public list of all folders for convenience
+        self.folders = list(self._folders_by_name.values())
+
+        self._projects_by_name: Dict[str, Project] = {p.name: p for p in projects}
+
+    @classmethod
+    def load(
+        cls,
+        ctx_ignored=None,
+        display_names: Optional[List[str]] = None,
+        via_resource_manager: bool = True,
+    ) -> "Hierarchy":
+        org_client = resourcemanager_v3.OrganizationsClient()
+        project_client = resourcemanager_v3.ProjectsClient()
+
+        # Load Orgs
+        org_nodes = []
+        try:
+            page_result = org_client.search_organizations(
+                request=resourcemanager_v3.SearchOrganizationsRequest()
+            )
+            for org in page_result:
+                if display_names and org.display_name not in display_names:
+                    continue
+
+                node = OrganizationNode(organization=org)
+                org_nodes.append(node)
+
+                if via_resource_manager:
+                    cls._load_folders_rm(node)
+                else:
+                    cls._load_folders_asset(node)
+        except exceptions.PermissionDenied:
+            logger.warning("Permission denied searching organizations")
+        except Exception as e:
+            logger.error(f"Error searching organizations: {e}")
+
+        # Load Projects
+        all_projects = []
+        if via_resource_manager:
+            try:
+                # search_projects() lists all projects the user has access to
+                projects_pager = project_client.search_projects(
+                    request=resourcemanager_v3.SearchProjectsRequest()
+                )
+                for p_proto in projects_pager:
+                    # Find parent
+                    parent_org = None
+                    parent_folder = None
+
+                    if p_proto.parent.startswith("organizations/"):
+                        parent_org = next(
+                            (
+                                o
+                                for o in org_nodes
+                                if o.organization.name == p_proto.parent
+                            ),
+                            None,
+                        )
+                    elif p_proto.parent.startswith("folders/"):
+                        for o in org_nodes:
+                            if p_proto.parent in o.folders:
+                                parent_folder = o.folders[p_proto.parent]
+                                parent_org = o
+                                break
+
+                    proj = Project(
+                        name=p_proto.name,
+                        project_id=p_proto.project_id,
+                        display_name=p_proto.display_name or p_proto.project_id,
+                        parent=p_proto.parent,
+                        organization=parent_org,
+                        folder=parent_folder,
+                    )
+                    all_projects.append(proj)
+            except exceptions.PermissionDenied:
+                logger.warning("Permission denied searching projects")
+            except Exception as e:
+                logger.error(f"Error searching projects: {e}")
+        else:
+            # Asset API mode
+            for org_node in org_nodes:
+                all_projects.extend(cls._load_projects_asset(org_node))
+
+            # Asset API Query REQUIRES a parent (like organization).
+            # To find organizationless projects, we always fallback to Resource Manager search_projects.
+            existing_project_names = {p.name for p in all_projects}
+            try:
+                projects_pager = project_client.search_projects(
+                    request=resourcemanager_v3.SearchProjectsRequest()
+                )
+                for p_proto in projects_pager:
+                    if p_proto.name in existing_project_names:
+                        continue
+
+                    # A project is organizationless if it's not under an organization or folder.
+                    is_orgless = not p_proto.parent.startswith(
+                        "organizations/"
+                    ) and not p_proto.parent.startswith("folders/")
+
+                    if is_orgless:
+                        proj = Project(
+                            name=p_proto.name,
+                            project_id=p_proto.project_id,
+                            display_name=p_proto.display_name or p_proto.project_id,
+                            parent=p_proto.parent,
+                            organization=None,
+                            folder=None,
+                        )
+                        all_projects.append(proj)
+            except exceptions.PermissionDenied:
+                logger.warning("Permission denied searching organizationless projects")
+            except Exception as e:
+                logger.error(f"Error searching organizationless projects: {e}")
+
+        return cls(organizations=org_nodes, projects=all_projects)
+
+    @staticmethod
+    def _load_folders_rm(node: OrganizationNode):
+        folders_client = resourcemanager_v3.FoldersClient()
+
+        def recurse(parent_name: str, ancestors: List[str]):
+            request = resourcemanager_v3.ListFoldersRequest(parent=parent_name)
+            try:
+                page = folders_client.list_folders(request=request)
+                for folder_proto in page:
+                    # ancestors list includes: [folder.Name, parent..., OrgName]
+                    new_ancestors = [folder_proto.name] + ancestors
+
+                    f = Folder(
+                        name=folder_proto.name,
+                        display_name=folder_proto.display_name,
+                        ancestors=new_ancestors,
+                        organization=node,
+                    )
+                    node.folders[f.name] = f
+                    recurse(f.name, new_ancestors)
+            except exceptions.PermissionDenied:
+                logger.warning(f"Permission denied listing folders for {parent_name}")
+
+        # Start recursion with Org
+        # ancestors initially just the Org
+        recurse(node.organization.name, [node.organization.name])
+
+    @staticmethod
+    def _load_folders_asset(node: OrganizationNode):
+        asset_client = asset_v1.AssetServiceClient()
+        # "SELECT name, resource.data.displayName, ancestors FROM `cloudresourcemanager_googleapis_com_Folder`"
+
+        statement = "SELECT name, resource.data.displayName, ancestors FROM `cloudresourcemanager_googleapis_com_Folder`"
+        query_request = asset_v1.QueryAssetsRequest(
+            parent=node.organization.name,
+            query=asset_v1.QueryAssetsRequest.Statement(statement=statement),
+        )
+
+        response = asset_client.query_assets(request=query_request)
+
+        for page in response.pages:
+            if not page.query_result or not page.query_result.rows:
+                continue
+
+            for row in page.query_result.rows:
+                # The Asset API SQL results are returned in a Struct where the values
+                # are in a list named 'f', similar to BigQuery JSON output.
+                # 0: name, 1: displayName, 2: ancestors
+
+                row_dict = dict(row.fields)
+                if "f" not in row_dict:
+                    continue
+
+                try:
+                    f_list = row_dict["f"].list_value.values
+                    if len(f_list) < 3:
+                        logger.warning(f"Unexpected number of columns in Asset API row: {len(f_list)}")
+                        continue
+
+                    name_val = f_list[0].struct_value.fields["v"].string_value
+                    display_name = f_list[1].struct_value.fields["v"].string_value
+                    ancestors_val = f_list[2].struct_value.fields["v"].list_value.values
+
+                    if not name_val or not display_name:
+                        continue
+
+                    name = _clean_asset_name(name_val)
+                    raw_ancestors = [_clean_asset_name(item.struct_value.fields["v"].string_value) for item in ancestors_val]
+
+                    # Ensure consistency with _load_folders_rm structure: [self, parent, ..., org]
+                    if not raw_ancestors or raw_ancestors[0] != name:
+                        ancestors = [name] + raw_ancestors
+                    else:
+                        ancestors = raw_ancestors
+
+                    f = Folder(
+                        name=name,
+                        display_name=display_name,
+                        ancestors=ancestors,
+                        organization=node
+                    )
+                    node.folders[f.name] = f
+                except (AttributeError, KeyError, IndexError) as e:
+                    logger.warning(f"Failed to parse Asset API row: {e}")
+                    continue
+
+    @staticmethod
+    def _load_projects_asset(node: OrganizationNode) -> List[Project]:
+        asset_client = asset_v1.AssetServiceClient()
+        projects = []
+        # Query Projects
+        statement = "SELECT name, resource.data.projectNumber, resource.data.projectId, resource.data.displayName, ancestors FROM `cloudresourcemanager_googleapis_com_Project`"
+        query_request = asset_v1.QueryAssetsRequest(
+            parent=node.organization.name,
+            query=asset_v1.QueryAssetsRequest.Statement(statement=statement),
+        )
+
+        try:
+            response = asset_client.query_assets(request=query_request)
+            for page in response.pages:
+                if not page.query_result or not page.query_result.rows:
+                    continue
+
+                for row in page.query_result.rows:
+                    row_dict = dict(row.fields)
+                    if "f" not in row_dict:
+                        continue
+
+                    f_list = row_dict["f"].list_value.values
+                    if len(f_list) < 5:
+                        logger.warning(
+                            f"Unexpected number of columns in Asset API project row: {len(f_list)}"
+                        )
+                        continue
+
+                    # 0: name, 1: projectNumber, 2: projectId, 3: displayName, 4: ancestors
+                    name_val = f_list[0].struct_value.fields["v"].string_value
+                    project_id = f_list[2].struct_value.fields["v"].string_value
+                    display_name = (
+                        f_list[3].struct_value.fields["v"].string_value or project_id
+                    )
+                    ancestors_val = f_list[4].struct_value.fields["v"].list_value.values
+
+                    name = _clean_asset_name(name_val)
+                    raw_ancestors = [
+                        _clean_asset_name(item.struct_value.fields["v"].string_value)
+                        for item in ancestors_val
+                    ]
+
+                    # For projects, we want the first ancestor that is NOT the project itself.
+                    # Typically raw_ancestors[0] is the parent, but if it's the project itself, pick [1].
+                    if raw_ancestors and raw_ancestors[0] == name:
+                        parent_res = (
+                            raw_ancestors[1]
+                            if len(raw_ancestors) > 1
+                            else node.organization.name
+                        )
+                    else:
+                        parent_res = (
+                            raw_ancestors[0]
+                            if raw_ancestors
+                            else node.organization.name
+                        )
+
+                    parent_folder = None
+                    if parent_res.startswith("folders/"):
+                        parent_folder = node.folders.get(parent_res)
+
+                    proj = Project(
+                        name=name,
+                        project_id=project_id,
+                        display_name=display_name,
+                        parent=parent_res,
+                        organization=node,
+                        folder=parent_folder,
+                    )
+                    projects.append(proj)
+        except Exception as e:
+            logger.error(f"Error querying projects via Asset API: {e}")
+
+        return projects
+
+    @staticmethod
+    def _parse_path(path: str) -> tuple[str, str]:
+        """Parse //org_name/path format without being fragile to urlparse semantics."""
+        if not path.startswith("//"):
+            raise PathParsingError("Path must start with //")
+
+        trimmed = path[2:]
+        if not trimmed:
+            raise PathParsingError("Path must contain an organization name (e.g., //example.com)")
+
+        parts = trimmed.split("/", 1)
+        org_name = parts[0]
+        resource_path = "/" + parts[1] if len(parts) > 1 else "/"
+        return org_name, resource_path
+
+    def get_resource_name(self, path: str) -> str:
+        org_name, resource_path = self._parse_path(path)
+
+        # Reserved for organizationless scope
+        if org_name == "_":
+            # Search in organizationless projects
+            for proj in self.projects:
+                if not proj.organization and proj.path == path:
+                    return proj.name
+            raise ResourceNotFoundError(f"Project path '{path}' not found in organizationless scope")
+
+        org_node = next(
+            (o for o in self.organizations if o.organization.display_name == org_name),
+            None,
+        )
+        if not org_node:
+            raise ResourceNotFoundError(f"Organization '{org_name}' not found")
+
+        if resource_path == "/":
+            return org_node.organization.name
+
+        try:
+            return org_node.get_resource_name(resource_path)
+        except ResourceNotFoundError:
+            # Maybe it's a project at the end of the path?
+            for proj in self.projects:
+                if proj.organization == org_node and proj.path == path:
+                    return proj.name
+            raise
+
+    def get_path_by_resource_name(self, resource_name: str) -> str:
+        if resource_name.startswith("organizations/"):
+            org = self._orgs_by_name.get(resource_name)
+            if org:
+                return "//" + path_escape(org.organization.display_name)
+            raise ResourceNotFoundError(f"Organization '{resource_name}' not found")
+
+        if resource_name.startswith("folders/"):
+            folder = self._folders_by_name.get(resource_name)
+            if folder:
+                return folder.path
+            raise ResourceNotFoundError(f"Folder '{resource_name}' not found")
+
+        if resource_name.startswith("projects/"):
+            proj = self._projects_by_name.get(resource_name)
+            if proj:
+                return proj.path
+            raise ResourceNotFoundError(f"Project '{resource_name}' not found")
+
+        raise ResourceNotFoundError(f"Unsupported resource name '{resource_name}'")

gcpath-0.1.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: gcpath
+Version: 0.1.0
+Summary: A CLI utility to manage Google Cloud Platform resource hierarchy paths.
+Project-URL: Homepage, https://github.com/tardigrde/gcpath
+Project-URL: Repository, https://github.com/tardigrde/gcpath
+Project-URL: Issues, https://github.com/tardigrde/gcpath/issues
+Author-email: Levente <leventetsk@proton.me>
+License-File: LICENSE
+Keywords: folders,gcp,google-cloud,hierarchy,projects
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: google-cloud-asset>=4.1.0
+Requires-Dist: google-cloud-resource-manager>=1.15.0
+Requires-Dist: rich>=14.2.0
+Requires-Dist: typer>=0.20.1
+Description-Content-Type: text/markdown
+
+# gcpath
+
+`gcpath` is a CLI utility to manage Google Cloud Platform resource hierarchy paths.
+It helps you translate between GCP resource names (e.g., `folders/12345`) and human-readable paths (e.g., `//example.com/department/team`).
+
+## Features
+
+- **Recursive Listing**: List all folders in your organization as paths.
+- **Path Resolution**: Get the resource name (ID) for a given path.
+- **Reverse Lookup**: Get the path for a given resource name (ID).
+- **Dual Mode**:
+    - **Cloud Asset API (Default)**: Fast, bulk loading using GCP Cloud Asset Inventory.
+    - **Resource Manager API**: Iterative loading using standard Resource Manager API (slower, but different permissions).
+
+## Quick Start
+
+After installation, ensure you are authenticated with Google Cloud and have the necessary permissions.
+
+```bash
+# List all resources
+gcpath ls
+
+# Find ID of a specific path
+gcpath name //example.com/engineering
+
+# Find path of a specific resource ID
+gcpath path folders/123456789
+```
+
+## Authentication
+
+`gcpath` uses [Google Cloud Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
+### Setup
+1. Install [gcloud CLI](https://cloud.google.com/sdk/docs/install).
+2. Authenticate:
+   ```bash
+   gcloud auth application-default login
+   ```
+
+For service accounts in CI/CD environments:
+```bash
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
+```
+
+## Usage
+
+### List Folders
+
+Recursively list all folders in your organization(s):
+
+```bash
+gcpath ls
+```
+
+Output:
+```
+//example.com/engineering
+//example.com/engineering/backend
+//example.com/sales
+...
+```
+
+You can also filter by organization display name:
+
+```bash
+gcpath ls "example.com"
+```
+
+### Get Resource Name
+
+Get the GCP resource name (e.g., `folders/123`) from a path:
+
+```bash
+gcpath name //example.com/engineering/backend
+# Output: folders/987654321
+```
+
+To get just the ID:
+
+```bash
+gcpath name --id //example.com/engineering/backend
+# Output: 987654321
+```
+
+### Get Path
+
+Get the path from a resource name:
+
+```bash
+gcpath path folders/987654321
+# Output: //example.com/engineering/backend
+```
+
+### Tree View
+
+Visualize the hierarchy in a tree format:
+
+```bash
+gcpath tree
+```
+
+Options:
+- `-L, --level N`: Limit depth of the tree.
+- `-i, --ids`: Include resource IDs in the output.
+
+### Modes
+
+By default, `gcpath` uses the Cloud Asset API which is faster for large hierarchies.
+To force using the Resource Manager API (iterative), use the `-U` / `--no-use-asset-api` flag:
+
+```bash
+gcpath ls -U
+```
+
+## Permissions
+
+### Cloud Asset API (Default)
+Requires `cloudasset.assets.searchAllResources` permission on the Organization.
+
+### Resource Manager API
+Requires `resourcemanager.folders.list` on the Organization and folders.
+
+## Development
+
+Prerequisites: `uv` (https://github.com/astral-sh/uv).
+
+1. Clone the repository.
+2. Install dependencies:
+   ```bash
+   uv sync
+   ```
+3. Run tests:
+   ```bash
+   uv run pytest
+   ```
+
+## License
+
+MIT

gcpath-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+gcpath/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gcpath/cli.py,sha256=nL9JosbKp0MECb4wI2ob7CAsTJOF0FCdsxo2KdoLLbw,9546
+gcpath/core.py,sha256=m-1XSVWzeXLRyzTJ0kejDiMixeG858h-PD1CWencFqs,19328
+gcpath-0.1.0.dist-info/METADATA,sha256=ktf5VCOKVLN5YcFv6ukL8ZQT23MqaHucMxwxD7vzIzc,3945
+gcpath-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+gcpath-0.1.0.dist-info/entry_points.txt,sha256=lnMH6BCByB_hACZeIF7qZgIvAqx7Oi-7rjY1mtgGf50,42
+gcpath-0.1.0.dist-info/licenses/LICENSE,sha256=j5EIx0ailzm4TAREZutbkNBko7nLs59vs8D0nGScos0,1071
+gcpath-0.1.0.dist-info/RECORD,,

gcpath-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

gcpath-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gcpath = gcpath.cli:run

gcpath-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Levente Csőke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.