cli/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is the SecNex Automation CLI, a command-line interface for automating interactions with the SecNex cloud environment. The CLI provides tenant and user management capabilities with a PostgreSQL backend and interactive terminal interface.

Development Policy

AI-Assisted Development

• No AI Attribution: Do not add "Authored-By", "Co-Authored-By", "Generated with Claude Code", or similar AI attribution in commits, code comments, or documentation
• Clean Code History: Maintain a clean git history without AI-generated commit messages or attributions
• Professional Standards: All code should be written to professional standards without explicit references to AI assistance

Development Commands

Running the CLI

# Run from project root
python src/secnex-cli/index.py

# Tenant management examples
python src/secnex-cli/index.py tenant create
python src/secnex-cli/index.py tenant list
python src/secnex-cli/index.py tenant delete --name "tenant-name"

# User management examples
python src/secnex-cli/index.py user create

Dependencies

The project uses external dependencies but lacks formal dependency management. Key dependencies:

• psycopg2 - PostgreSQL database adapter
• rich - Terminal formatting and tables
• questionary - Interactive command-line prompts
• argon2-cffi - Password hashing with Argon2 algorithm

Install dependencies manually:

pip install psycopg2-binary rich questionary argon2-cffi

Project Architecture

Entry Point (src/secnex-cli/index.py)

• Main Class: SecNexCLI - Initializes database connection and sets up command parsing
• Database: Hardcoded PostgreSQL connection (localhost:5432, database="api", user="postgres", password="postgres")
• Command Pattern: Uses argparse subparsers with separate Parser and Command classes
• Match/Case: Python 3.10+ match-case syntax for command dispatch

Command Structure

The CLI follows a Parser/Command pattern:

• Parser Classes (cmd/tenant.py, cmd/user.py): Define argparse structure and command-line arguments
• Command Classes: Implement business logic and database operations
• Database Layer (database/): Centralized connection management and configuration

Database Schema

• Primary Table: core.tenants with fields: id, name, enabled, created_at, deleted_at
• Soft Deletion: Uses deleted_at timestamp for soft deletes
• Connection Management: Direct psycopg2 connections with manual cursor management

Tenant Commands (Fully Implemented)

• tenant create - Interactive tenant creation with rich table output
• tenant list - Lists active tenants in formatted table
• tenant get --name <tenant> - Retrieves specific tenant details
• tenant delete --name <tenant> [--force] - Soft delete (default) or hard delete with --force
• tenant enable/disable --name <tenant> - Tenant state management
• tenant restore --name <tenant> - Restore soft-deleted tenants

User Commands (Fully Implemented)

• user create - Interactive user creation with password hashing, tenant selection, and rich table output

Key Implementation Details

UI/UX Features

• Rich Tables: Uses rich.Table for formatted terminal output with emojis (✅/❌ for enabled/disabled)
• Interactive Prompts: Uses questionary for text input, password fields, and selection dropdowns
• Cancellation Handling: Proper handling when users cancel prompts (Ctrl+C or ESC)

Database Patterns

• Parameterized Queries: All database operations use parameterized queries to prevent SQL injection
• Manual Connection Management: Explicit cursor creation, commit, and close operations
• Error Handling: Basic database connection error handling with graceful exits

Security Features

• Argon2 Password Hashing: Uses Argon2 algorithm for secure password storage with configurable parameters
• Secure Hash Configuration: Time cost 3, memory cost 64MB, parallelism 4, 32-byte hash, 16-byte salt
• Password Verification: Includes verification and rehash checking capabilities in utils/hash.py
• Transaction Management: Proper rollback on database errors to maintain data integrity

Code Organization

• Type Hints: Consistent use of Python type hints throughout codebase
• Separation of Concerns: Clear separation between parsing, command execution, and database operations
• Interactive vs Non-interactive: Commands support both argument-based and interactive input

Critical Missing Components

Dependency Management

• No requirements.txt or pyproject.toml exists
• Dependencies must be installed manually
• No version pinning or dependency resolution

Configuration Management

• Database credentials are hardcoded in index.py:9-15
• No environment variable support or config file loading
• No development/production configuration separation

Incomplete Features

• No error handling for database constraint violations (duplicate tenants, etc.)
• No logging or audit trail functionality
• No user authentication/login functionality (only user creation)

Development Infrastructure

• No test framework or test files
• No linting configuration (flake8, black, etc.)
• No CI/CD pipeline configuration
• No shell completion support

Database Connection Requirements

The CLI requires a running PostgreSQL instance with:

• Database name: api
• Tables:
  • core.tenants with schema: id, name, enabled, created_at, deleted_at
  • auth.users with schema: id, tenant_id, name, email, password, created_at, enabled
• User: postgres with password postgres on localhost:5432 (hardcoded)

Future Development Priorities

1. Add formal dependency management (requirements.txt or pyproject.toml)
2. Implement configuration system for database connections and CLI settings
3. Complete user management functionality
4. Add comprehensive error handling and validation
5. Implement testing framework with unit and integration tests
6. Add environment variable support for configuration