Merge pull request #53 from zomglings/rolodex

Implement rolodex: local cache for users and channels

Author: zomglings

README.md

@@ -160,6 +160,40 @@ clacks recent
 clacks recent -l 50
 ```
 
+## Rolodex
+
+Manage aliases for users and channels. Aliases resolve to platform-specific IDs (e.g., Slack user IDs).
+
+Sync from Slack API:
+```bash
+clacks rolodex sync
+```
+
+Add alias manually:
+```bash
+clacks rolodex add <alias> -t <target-id> -T <target-type>
+clacks rolodex add kartik -t U03QPJ2KMJ6 -T user
+clacks rolodex add dev-channel -t C08740LGAE6 -T channel
+```
+
+List aliases:
+```bash
+clacks rolodex list
+clacks rolodex list -T user
+clacks rolodex list -p slack
+```
+
+Remove alias:
+```bash
+clacks rolodex remove <alias> -T <target-type>
+```
+
+Show valid target types for a platform:
+```bash
+clacks rolodex platforminfo -p slack
+clacks rolodex platforminfo -p github
+```
+
 ## Output
 
 All commands output JSON to stdout. Redirect to file:

operations/rolodex/README.md

@@ -0,0 +1,61 @@
+# Rolodex Implementation
+
+## Overview
+
+Local alias database for resolving human-friendly names to platform-specific IDs. Supports multiple platforms (Slack, GitHub) with platform-specific target types.
+
+## Database Schema
+
+Single table: `aliases`
+
+| Column | Type | Notes |
+|--------|------|-------|
+| alias | String | Primary key (composite) |
+| context | String | Primary key (composite) - auth context name |
+| target_type | String | Primary key (composite) - e.g., user, channel |
+| platform | String | Platform name (slack, github) |
+| target_id | String | Platform-specific ID (e.g., U0876FVQ58C) |
+
+Unique constraint: (alias, context, target_type)
+
+## Platforms and Target Types
+
+Defined in `rolodex/data.py`:
+
+- **slack**: user, channel
+- **github**: user, repo, org
+
+## CLI Commands
+
+```bash
+clacks rolodex add <alias> -t <target-id> -T <target-type> [-p <platform>]
+clacks rolodex list [-p <platform>] [-T <target-type>] [-t <target-id>]
+clacks rolodex remove <alias> -T <target-type>
+clacks rolodex sync
+clacks rolodex platforminfo -p <platform>
+```
+
+## Resolution Flow
+
+`resolve_user_id` and `resolve_channel_id` in `messaging/operations.py`:
+
+1. Check if already a Slack ID (U..., C..., D..., G...)
+2. Check rolodex aliases (filtered by platform)
+3. Fall back to Slack API
+
+## File Structure
+
+```
+src/slack_clacks/rolodex/
+  __init__.py
+  data.py        # Platform and target type constants
+  models.py      # SQLAlchemy Alias model
+  operations.py  # Database operations
+  cli.py         # CLI commands
+```
+
+## Related Issues
+
+- #38 - clacks rolodex (design doc)
+- #50 - Add user and channel lookup commands
+- #18 - Cache channel and user metadata in database

operations/rolodex/checklist.md

@@ -0,0 +1,45 @@
+# Rolodex Implementation Checklist
+
+## Schema
+
+Single table: `aliases`
+
+```
+aliases:
+  alias        String      PK
+  context      String      PK
+  target_type  String      PK
+  platform     String
+  target_id    String
+```
+
+Unique per (alias, context, target_type).
+
+## CLI Commands
+
+- [x] `clacks rolodex add` - add an alias
+- [x] `clacks rolodex list` - list aliases with filters (-p platform, -T target_type, -t target_id)
+- [x] `clacks rolodex remove` - remove an alias
+- [x] `clacks rolodex sync` - sync from Slack API
+- [x] `clacks rolodex platforminfo` - show valid target types for a platform
+
+## Operations
+
+- [x] `add_alias()` - add or update an alias
+- [x] `get_alias()` - lookup by (alias, context, target_type)
+- [x] `list_aliases()` - list with filters
+- [x] `remove_alias()` - delete an alias
+- [x] `resolve_alias()` - resolve identifier in context
+- [x] `sync_from_slack()` - sync users and channels from Slack API
+- [x] `validate_platform_target_type()` - validate platform/target_type combinations
+- [x] `get_platform_target_types()` - get valid target types for platform
+
+## Resolution
+
+- [x] `resolve_user_id()` checks aliases first, then falls back to Slack API
+- [x] `resolve_channel_id()` checks aliases first, then falls back to Slack API
+
+## Finalization
+
+- [x] Run all checks (ruff, mypy, tests)
+- [x] Commit and update PR

pyproject.toml

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

src/slack_clacks/alembic/versions/a1b2c3d4e5f6_add_aliases_table.py

@@ -0,0 +1,53 @@
+"""add aliases table
+
+Revision ID: a1b2c3d4e5f6
+Revises: 6713eb6c63d1
+Create Date: 2026-01-08 12:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "a1b2c3d4e5f6"
+down_revision: Union[str, Sequence[str], None] = "6713eb6c63d1"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Create aliases table with FK to contexts."""
+    op.create_table(
+        "aliases",
+        sa.Column("alias", sa.String(), nullable=False),
+        sa.Column("context", sa.String(), nullable=False),
+        sa.Column("target_type", sa.String(), nullable=False),
+        sa.Column("platform", sa.String(), nullable=False),
+        sa.Column("target_id", sa.String(), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["context"],
+            ["contexts.name"],
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("alias", "context", "target_type"),
+    )
+    op.create_index(
+        "ix_aliases_platform_target",
+        "aliases",
+        ["platform", "target_id"],
+    )
+    op.create_index(
+        "ix_aliases_context",
+        "aliases",
+        ["context"],
+    )
+
+
+def downgrade() -> None:
+    """Drop aliases table."""
+    op.drop_index("ix_aliases_context", table_name="aliases")
+    op.drop_index("ix_aliases_platform_target", table_name="aliases")
+    op.drop_table("aliases")

src/slack_clacks/cli.py

@@ -10,6 +10,7 @@
     generate_recent_parser,
     generate_send_parser,
 )
+from slack_clacks.rolodex.cli import generate_cli as generate_rolodex_cli
 
 
 def generate_cli() -> argparse.ArgumentParser:
@@ -37,6 +38,14 @@ def generate_cli() -> argparse.ArgumentParser:
         "auth", parents=[auth_parser], add_help=False, help=auth_parser.description
     )
 
+    rolodex_parser = generate_rolodex_cli()
+    subparsers.add_parser(
+        "rolodex",
+        parents=[rolodex_parser],
+        add_help=False,
+        help=rolodex_parser.description,
+    )
+
     send_parser = generate_send_parser()
     subparsers.add_parser(
         "send",

src/slack_clacks/messaging/cli.py

@@ -38,9 +38,9 @@ def handle_send(args: argparse.Namespace) -> None:
         channel_id = None
 
         if args.channel:
-            channel_id = resolve_channel_id(client, args.channel)
+            channel_id = resolve_channel_id(client, args.channel, session, context.name)
         elif args.user:
-            user_id = resolve_user_id(client, args.user)
+            user_id = resolve_user_id(client, args.user, session, context.name)
             channel_id = open_dm_channel(client, user_id)
             if channel_id is None:
                 raise ValueError(f"Failed to open DM with user '{args.user}'.")
@@ -116,7 +116,7 @@ def handle_read(args: argparse.Namespace) -> None:
         channel_id = None
 
         if args.channel:
-            channel_id = resolve_channel_id(client, args.channel)
+            channel_id = resolve_channel_id(client, args.channel, session, context.name)
 
             scopes = get_scopes_for_mode(context.app_type)
             if channel_id.startswith("C"):
@@ -125,7 +125,7 @@ def handle_read(args: argparse.Namespace) -> None:
                 validate("groups:history", scopes, raise_on_error=True)
 
         elif args.user:
-            user_id = resolve_user_id(client, args.user)
+            user_id = resolve_user_id(client, args.user, session, context.name)
             channel_id = open_dm_channel(client, user_id)
             if channel_id is None:
                 raise ValueError(f"Failed to open DM with user '{args.user}'.")
@@ -264,9 +264,9 @@ def handle_react(args: argparse.Namespace) -> None:
         client = create_client(context.access_token, context.app_type)
 
         if args.channel:
-            channel_id = resolve_channel_id(client, args.channel)
+            channel_id = resolve_channel_id(client, args.channel, session, context.name)
         else:
-            user_id = resolve_user_id(client, args.user)
+            user_id = resolve_user_id(client, args.user, session, context.name)
             dm_channel = open_dm_channel(client, user_id)
             if dm_channel is None:
                 raise ValueError(f"Failed to open DM with user '{args.user}'.")
@@ -352,9 +352,9 @@ def handle_delete(args: argparse.Namespace) -> None:
         client = create_client(context.access_token, context.app_type)
 
         if args.channel:
-            channel_id = resolve_channel_id(client, args.channel)
+            channel_id = resolve_channel_id(client, args.channel, session, context.name)
         else:
-            user_id = resolve_user_id(client, args.user)
+            user_id = resolve_user_id(client, args.user, session, context.name)
             dm_channel = open_dm_channel(client, user_id)
             if dm_channel is None:
                 raise ValueError(f"Failed to open DM with user '{args.user}'.")

src/slack_clacks/messaging/operations.py

@@ -4,27 +4,44 @@
 
 from slack_sdk import WebClient
 from slack_sdk.errors import SlackApiError
+from sqlalchemy.orm import Session
 
 from slack_clacks.messaging.exceptions import (
     ClacksChannelNotFoundError,
     ClacksUserNotFoundError,
 )
 
 
-def resolve_channel_id(client: WebClient, channel_identifier: str) -> str:
+def resolve_channel_id(
+    client: WebClient,
+    channel_identifier: str,
+    session: Session | None = None,
+    context_name: str | None = None,
+) -> str:
     """
     Resolve channel identifier to channel ID.
-    Accepts channel ID (C...), channel name (#general or general).
+    Accepts channel ID (C..., D..., G...), channel name (#general or general), or alias.
     Returns channel ID or raises ClacksChannelNotFoundError if not found.
+
+    Resolution order:
+    1. Check if already a Slack channel ID (C..., D..., G...)
+    2. Check aliases (if session and context_name provided)
+    3. Fall back to Slack API
     """
-    if channel_identifier.startswith("C") or channel_identifier.startswith("D"):
+    if channel_identifier.startswith(("C", "D", "G")):
         return channel_identifier
 
     channel_name = channel_identifier.lstrip("#")
 
-    # TODO(zomglings): Implement pagination via response_metadata.next_cursor
-    # Currently only searches first page (up to 1000 channels)
-    # Plan: Cache channel list in database to avoid repeated API calls
+    # Check aliases first (requires context for security)
+    if session is not None and context_name is not None:
+        from slack_clacks.rolodex.operations import resolve_alias
+
+        alias = resolve_alias(session, channel_name, context_name, "channel", "slack")
+        if alias:
+            return alias.target_id
+
+    # Fall back to API call
     try:
         response = client.conversations_list(
             types="public_channel,private_channel", limit=1000
@@ -38,20 +55,36 @@ def resolve_channel_id(client: WebClient, channel_identifier: str) -> str:
     raise ClacksChannelNotFoundError(channel_identifier)
 
 
-def resolve_user_id(client: WebClient, user_identifier: str) -> str:
+def resolve_user_id(
+    client: WebClient,
+    user_identifier: str,
+    session: Session | None = None,
+    context_name: str | None = None,
+) -> str:
     """
     Resolve user identifier to user ID.
-    Accepts user ID (U...), username (@username or username), or email.
+    Accepts user ID (U...), username (@username or username), email, or alias.
     Returns user ID or raises ClacksUserNotFoundError if not found.
+
+    Resolution order:
+    1. Check if already a Slack user ID (U...)
+    2. Check aliases (if session and context_name provided)
+    3. Fall back to Slack API
     """
     if user_identifier.startswith("U"):
         return user_identifier
 
     username = user_identifier.lstrip("@")
 
-    # TODO(zomglings): Implement pagination via response_metadata.next_cursor
-    # Currently only searches first page (100-200 users depending on tier)
-    # Plan: Cache user list in database to avoid repeated API calls
+    # Check aliases first (requires context for security)
+    if session is not None and context_name is not None:
+        from slack_clacks.rolodex.operations import resolve_alias
+
+        alias = resolve_alias(session, username, context_name, "user", "slack")
+        if alias:
+            return alias.target_id
+
+    # Fall back to API call
     try:
         response = client.users_list()
         for user in response["members"]:

src/slack_clacks/rolodex/__init__.py

@@ -0,0 +1,3 @@
+"""
+Rolodex: Local cache for user and channel metadata.
+"""