Merge pull request #72 from downstairs-dawgs/files-subcommand

Add clacks files subcommand group

Author: zomglings

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "slack-clacks"
-version = "0.7.0"
+version = "0.8.0"
 description = "the default mode of degenerate communication."
 readme = "README.md"
 license = { text = "MIT" }

src/slack_clacks/cli.py

@@ -3,6 +3,7 @@
 
 from slack_clacks.auth.cli import generate_cli as generate_auth_cli
 from slack_clacks.configuration.cli import generate_cli as generate_config_cli
+from slack_clacks.files.cli import generate_files_cli
 from slack_clacks.listen.cli import generate_listen_parser
 from slack_clacks.messaging.cli import (
     generate_delete_parser,
@@ -13,7 +14,6 @@
 )
 from slack_clacks.rolodex.cli import generate_cli as generate_rolodex_cli
 from slack_clacks.skill.cli import generate_cli as generate_skill_cli
-from slack_clacks.upload.cli import generate_upload_parser
 
 
 def generate_cli() -> argparse.ArgumentParser:
@@ -105,12 +105,12 @@ def generate_cli() -> argparse.ArgumentParser:
         help=listen_parser.description,
     )
 
-    upload_parser = generate_upload_parser()
+    files_parser = generate_files_cli()
     subparsers.add_parser(
-        "upload",
-        parents=[upload_parser],
+        "files",
+        parents=[files_parser],
         add_help=False,
-        help=upload_parser.description,
+        help=files_parser.description,
     )
 
     return parser

src/slack_clacks/files/__init__.py

@@ -0,0 +1,3 @@
+"""
+File download, listing, and info operations.
+"""

src/slack_clacks/files/cli.py

@@ -0,0 +1,240 @@
+"""
+CLI commands for file operations.
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import cast
+
+from slack_clacks.auth.client import create_client
+from slack_clacks.auth.validation import get_scopes_for_mode, validate
+from slack_clacks.configuration.database import (
+    ensure_db_updated,
+    get_current_context,
+    get_session,
+)
+from slack_clacks.files.operations import (
+    download_file_to_path,
+    download_file_to_stdout,
+    extract_file_id_from_permalink,
+    get_file_info,
+    list_files,
+)
+from slack_clacks.messaging.operations import resolve_channel_id, resolve_user_id
+from slack_clacks.upload.cli import generate_upload_parser
+
+
+def handle_download(args: argparse.Namespace) -> None:
+    ensure_db_updated(config_dir=args.config_dir)
+    with get_session(args.config_dir) as session:
+        context = get_current_context(session)
+        if context is None:
+            raise ValueError(
+                "No active authentication context. Authenticate with: clacks auth login"
+            )
+
+        scopes = get_scopes_for_mode(context.app_type)
+        validate("files:read", scopes, raise_on_error=True)
+
+        client = create_client(context.access_token, context.app_type)
+
+        # Resolve file ID
+        if args.file_id:
+            file_id = args.file_id
+        else:
+            file_id = extract_file_id_from_permalink(args.permalink)
+
+        # Get file metadata
+        info = cast(dict, get_file_info(client, file_id))
+        file_data = info.get("file", {})
+        filename = file_data.get("name", file_id)
+        download_url = file_data.get("url_private_download") or file_data.get(
+            "url_private"
+        )
+
+        if not download_url:
+            raise ValueError(f"No download URL available for file {file_id}")
+
+        # Download to stdout
+        if args.write == "-":
+            nbytes = download_file_to_stdout(
+                download_url, context.access_token, context.app_type
+            )
+            print(f"{filename}: {nbytes} bytes", file=sys.stderr)
+            return
+
+        # Determine output path
+        if args.write:
+            output_path = Path(args.write)
+        else:
+            output_path = Path(filename)
+
+        # Check for existing file
+        if output_path.exists() and not args.force:
+            raise FileExistsError(
+                f"File already exists: {output_path}. Use --force to overwrite."
+            )
+
+        nbytes = download_file_to_path(
+            download_url, context.access_token, context.app_type, output_path
+        )
+        print(f"{output_path}: {nbytes} bytes", file=sys.stderr)
+
+
+def handle_list(args: argparse.Namespace) -> None:
+    ensure_db_updated(config_dir=args.config_dir)
+    with get_session(args.config_dir) as session:
+        context = get_current_context(session)
+        if context is None:
+            raise ValueError(
+                "No active authentication context. Authenticate with: clacks auth login"
+            )
+
+        scopes = get_scopes_for_mode(context.app_type)
+        validate("files:read", scopes, raise_on_error=True)
+
+        client = create_client(context.access_token, context.app_type)
+
+        # Resolve channel/user identifiers to IDs
+        channel_id = None
+        if args.channel:
+            channel_id = resolve_channel_id(client, args.channel, session, context.name)
+
+        user_id = None
+        if args.user:
+            user_id = resolve_user_id(client, args.user, session, context.name)
+
+        result = list_files(
+            client, channel=channel_id, user=user_id, limit=args.limit, page=args.page
+        )
+        json.dump(result, sys.stdout)
+
+
+def handle_info(args: argparse.Namespace) -> None:
+    ensure_db_updated(config_dir=args.config_dir)
+    with get_session(args.config_dir) as session:
+        context = get_current_context(session)
+        if context is None:
+            raise ValueError(
+                "No active authentication context. Authenticate with: clacks auth login"
+            )
+
+        scopes = get_scopes_for_mode(context.app_type)
+        validate("files:read", scopes, raise_on_error=True)
+
+        client = create_client(context.access_token, context.app_type)
+
+        result = get_file_info(client, args.file_id)
+        json.dump(result, sys.stdout)
+
+
+def generate_files_cli() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Upload, download, list, and inspect files"
+    )
+    parser.set_defaults(func=lambda _: parser.print_help())
+
+    subparsers = parser.add_subparsers(dest="files_command")
+
+    # --- download ---
+    dl_parser = subparsers.add_parser("download", help="Download a file from Slack")
+    dl_parser.add_argument(
+        "-D",
+        "--config-dir",
+        type=str,
+        default=None,
+        help="Configuration directory",
+    )
+    id_group = dl_parser.add_mutually_exclusive_group(required=True)
+    id_group.add_argument(
+        "-i",
+        "--file-id",
+        type=str,
+        help="Slack file ID (e.g., F2147483862)",
+    )
+    id_group.add_argument(
+        "--permalink",
+        type=str,
+        help="Slack file permalink URL",
+    )
+    dl_parser.add_argument(
+        "-w",
+        "--write",
+        type=str,
+        default=None,
+        help="Output path (default: original filename in CWD, use - for stdout)",
+    )
+    dl_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite existing file without prompting",
+    )
+    dl_parser.set_defaults(func=handle_download)
+
+    # --- list ---
+    list_parser = subparsers.add_parser("list", help="List files")
+    list_parser.add_argument(
+        "-D",
+        "--config-dir",
+        type=str,
+        default=None,
+        help="Configuration directory",
+    )
+    list_parser.add_argument(
+        "-c",
+        "--channel",
+        type=str,
+        help="Filter by channel",
+    )
+    list_parser.add_argument(
+        "-u",
+        "--user",
+        type=str,
+        help="Filter by user",
+    )
+    list_parser.add_argument(
+        "-l",
+        "--limit",
+        type=int,
+        default=20,
+        help="Max files to list (default: 20)",
+    )
+    list_parser.add_argument(
+        "-p",
+        "--page",
+        type=int,
+        default=1,
+        help="Page number (default: 1)",
+    )
+    list_parser.set_defaults(func=handle_list)
+
+    # --- info ---
+    info_parser = subparsers.add_parser("info", help="Show file metadata")
+    info_parser.add_argument(
+        "-D",
+        "--config-dir",
+        type=str,
+        default=None,
+        help="Configuration directory",
+    )
+    info_parser.add_argument(
+        "-i",
+        "--file-id",
+        type=str,
+        required=True,
+        help="Slack file ID (e.g., F2147483862)",
+    )
+    info_parser.set_defaults(func=handle_info)
+
+    # --- upload ---
+    upload_parser = generate_upload_parser()
+    subparsers.add_parser(
+        "upload",
+        parents=[upload_parser],
+        add_help=False,
+        help=upload_parser.description,
+    )
+
+    return parser

src/slack_clacks/files/operations.py

@@ -0,0 +1,105 @@
+"""
+Core file operations using Slack Web API.
+"""
+
+import re
+import sys
+import urllib.request
+from pathlib import Path
+
+from slack_sdk import WebClient
+
+from slack_clacks.auth.constants import MODE_COOKIE
+
+_CHUNK_SIZE = 8192
+
+
+def get_file_info(client: WebClient, file_id: str) -> dict | bytes:
+    """Get file metadata from Slack."""
+    response = client.files_info(file=file_id)
+    return response.data
+
+
+def list_files(
+    client: WebClient,
+    channel: str | None = None,
+    user: str | None = None,
+    limit: int = 20,
+    page: int = 1,
+) -> dict | bytes:
+    """List files, optionally filtered by channel and/or user."""
+    kwargs: dict = {"count": limit, "page": page}
+    if channel:
+        kwargs["channel"] = channel
+    if user:
+        kwargs["user"] = user
+    response = client.files_list(**kwargs)
+    return response.data
+
+
+def extract_file_id_from_permalink(url: str) -> str:
+    """
+    Extract a Slack file ID from a permalink URL.
+
+    Supports formats like:
+    - https://workspace.slack.com/files/U.../F2147483862/filename.txt
+    - https://files.slack.com/files-pri/T.../F2147483862/filename.txt
+    """
+    match = re.search(r"/(F[A-Z0-9]+)", url)
+    if not match:
+        raise ValueError(f"Could not extract file ID from URL: {url}")
+    return match.group(1)
+
+
+def _build_download_headers(access_token: str, app_type: str) -> dict[str, str]:
+    """Build HTTP headers for downloading a private Slack file."""
+    if app_type == MODE_COOKIE:
+        if "|" in access_token:
+            token, cookie = access_token.split("|", 1)
+            return {
+                "Authorization": f"Bearer {token}",
+                "Cookie": f"d={cookie}",
+            }
+        else:
+            raise ValueError(
+                "Cookie mode requires token in format: xoxc-token|d-cookie-value"
+            )
+    return {"Authorization": f"Bearer {access_token}"}
+
+
+def download_file_to_path(
+    url: str, access_token: str, app_type: str, output_path: Path
+) -> int:
+    """
+    Download a file from Slack to a local path.
+    Returns the number of bytes written.
+    """
+    headers = _build_download_headers(access_token, app_type)
+    req = urllib.request.Request(url, headers=headers)
+    total = 0
+    with urllib.request.urlopen(req) as resp, open(output_path, "wb") as f:
+        while True:
+            chunk = resp.read(_CHUNK_SIZE)
+            if not chunk:
+                break
+            f.write(chunk)
+            total += len(chunk)
+    return total
+
+
+def download_file_to_stdout(url: str, access_token: str, app_type: str) -> int:
+    """
+    Download a file from Slack and write it to stdout.
+    Returns the number of bytes written.
+    """
+    headers = _build_download_headers(access_token, app_type)
+    req = urllib.request.Request(url, headers=headers)
+    total = 0
+    with urllib.request.urlopen(req) as resp:
+        while True:
+            chunk = resp.read(_CHUNK_SIZE)
+            if not chunk:
+                break
+            sys.stdout.buffer.write(chunk)
+            total += len(chunk)
+    return total