Skip to content

CLAUDE.md

Latest commit

 

History

History
243 lines (192 loc) · 12.9 KB

CLAUDE.md

File metadata and controls

243 lines (192 loc) · 12.9 KB

CLAUDE.md

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

Commands

Testing

  • ./test-all.sh <scene_id> <env> - Run comprehensive tests for scene and object uploads (requires scene_id from previous upload)

Scene Operations

  • ./upload-scene.sh --scene_dir <dir> --scene_name <name> [--env prod|dev] [--scene_id <id>] [--verbose] [--dry_run] - Upload scene files with enhanced security and validation (--scene_name required for new scenes)
  • ./upload-scene.sh --help - Show usage information

Object Operations

  • ./upload-object.sh [--scene_id <id>] --object_filename <name> --object_dir <dir> [--object_id <id>] [--env prod|dev] [--verbose] [--dry_run] - Upload dynamic 3D objects (supports PNG, JPG, JPEG, WEBP textures)
  • ./upload-object-manifest.sh [--scene_id <id>] [--env prod|dev] [--verbose] [--dry_run] - Upload object manifest after object upload
  • ./list-objects.sh [--scene_id <id>] --env <env> --verbose - List objects for a scene

Dependencies

  • Requires jq and curl to be installed
  • Set C3D_DEVELOPER_API_KEY environment variable or use .env file (recommended)
  • Optional: Set C3D_SCENE_ID environment variable to avoid --scene_id parameters

Architecture

File Structure

  • Shell scripts: Main upload functionality in bash scripts with standardized logging, error handling, and API interaction patterns
  • Test directories: scene-test/, object-test/, lantern-test/ contain sample assets for testing uploads
  • Generated files: <scene_id>_object_manifest.json files are created automatically after object uploads

Key Components

  • sdk-version.txt: Contains current SDK version (1.1.0) used for generated settings.json. Kept in lockstep with ModuleVersion in C3DUploadTools.psd1.
  • settings.json: Scene configuration with scale, sceneName, and sdkVersion fields - generated automatically during upload with SDK prefix (cli-bash-v<version> or cli-powershell-v<version>)
  • API endpoints: Support both prod (cognitive3d.com) and dev (c3ddev.com) environments

Upload Workflow

  1. Upload scene first to get scene_id
  2. Upload objects using scene_id (can be set in .env file for convenience)
  3. Upload object manifest to display objects in dashboard
  4. Object manifests are automatically generated but can be manually edited before upload

Object Manifest Structure

The object manifest follows Unity SDK conventions. Each object entry has:

  • id: A unique UUID identifying this object instance (auto-generated if not provided)
  • mesh: The name of the 3D model file (e.g., "cube" for cube.gltf/cube.bin)
  • name: Display name for the object (defaults to mesh name)
  • scaleCustom: Scale factors [x, y, z]
  • initialPosition: Starting position [x, y, z]
  • initialRotation: Quaternion rotation [x, y, z, w]

Important: The id field is a UUID, not the mesh name. Multiple objects can share the same mesh but must have unique id values. When no --object_id is provided, scripts auto-generate a UUID.

Texture Format Support

  • Scene uploads support PNG, JPG, JPEG, and WEBP image files
  • Object uploads support PNG, JPG, JPEG, and WEBP texture files
  • Textures are automatically detected and uploaded with scene/object files
  • Object thumbnail must be named cvr_object_thumbnail.png (PNG format required)

Environment Variable Support (SDK-191) ✅

Streamlined Workflow with .env:

  • Set C3D_SCENE_ID in .env file to avoid --scene_id parameters
  • All object operations (upload-object.sh, upload-object-manifest.sh, list-objects.sh) support environment variable fallback
  • PowerShell module automatically loads .env file during import
  • Tested with real API uploads in both dev and prod environments

Common Patterns

  • All scripts use consistent argument parsing with --parameter value format
  • Standardized logging with color-coded output (INFO/WARN/ERROR/DEBUG) and timestamps
  • Comprehensive error checking for dependencies and required parameters
  • Support for --verbose and --dry_run flags across scripts

Enhanced upload-scene.sh Features

Security & Reliability

  • Secure API key handling without local storage exposure
  • Safe file operations with comprehensive validation
  • Automatic settings.json generation with SDK version prefixes
  • Comprehensive input validation (UUID format, semantic versioning, file size limits)
  • Cross-platform compatibility (macOS and Linux)

Advanced Error Handling

  • Specific guidance for HTTP 401 "Key expired" errors with step-by-step resolution
  • Authentication troubleshooting for general 401 errors
  • Clear messages for 403 (forbidden) and 404 (not found) errors
  • Actionable error messages that guide users to solutions

Validation Features

  • Scene ID must be valid UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  • SDK version must follow semantic versioning: x.y.z
  • File size validation with 100MB limit per file
  • Early validation prevents costly operations with invalid data

Logging & Monitoring

  • Timestamped logs with format: [YYYY-MM-DD HH:MM:SS] [LEVEL] message
  • Upload timing metrics and performance monitoring
  • File size reporting in debug mode
  • Color-coded output for different log levels

Safe Testing

  • --dry_run mode shows exact operations without execution
  • Previews curl commands with redacted API keys
  • Displays file inventory with sizes before upload
  • Validates all inputs before making any changes

Best Practices for Development

  • Always test with --dry_run first before real uploads
  • Use --verbose for detailed debugging information
  • Check file sizes if uploads are slow or failing
  • Rotate API keys immediately when receiving 401 errors
  • Validate scene_id format from dashboard before use

PowerShell Implementation (Windows Compatibility)

Status: Complete ✅ (Enterprise-Grade)

PowerShell module provides full Windows compatibility with enterprise-grade features and comprehensive validation.

Enterprise Features Implemented

Module Architecture ✅

  • Professional Organization: Functions categorized in Core, Validation, Api, Utilities directories
  • Type Safety: PowerShell classes for structured data (C3DConfiguration, C3DUploadRequest, C3DApiResponse)
  • Cross-platform compatibility: Windows PowerShell 5.1+ and PowerShell Core 7.x
  • Comprehensive validation: Advanced [ValidateScript()] blocks with detailed error messages
  • Error handling: Proper PowerShell error records with categories and recommended actions

Production-Ready Features ✅

  • Progress tracking: Visual feedback for large file uploads
  • Memory optimization: Efficient handling of large files without external dependencies
  • Comprehensive help: Detailed documentation with real-world examples and workflows
  • Security: Secure API key handling, HTTPS validation, no credential logging
  • Reliability: Automatic backup/rollback, retry logic, comprehensive input validation

PowerShell Commands

Testing (Located in C3DUploadTools/Tests/)

  • pwsh -File C3DUploadTools/Tests/test-module-structure.ps1 - Module structure validation
  • pwsh -File C3DUploadTools/Tests/test-utilities-internal.ps1 - Internal function testing
  • pwsh -File C3DUploadTools/Tests/test-scene-upload.ps1 - Scene upload workflow testing
  • pwsh -File C3DUploadTools/Tests/test-object-upload.ps1 - Object upload workflow testing

Module Usage (All Functions Complete ✅)

# Import the module
Import-Module ./C3DUploadTools -Force

# Available functions (all production-ready)
Upload-C3DScene -SceneDirectory <path> -SceneName <name> [-Environment prod|dev] [-SceneId <uuid>] [-DryRun] [-Verbose]    # ✅ COMPLETE (SceneName required for new scenes)
Upload-C3DObject -ObjectFilename <name> -ObjectDirectory <path> [-SceneId <uuid>] [-Environment prod|dev] [-DryRun]  # ✅ COMPLETE
Upload-C3DObjectManifest [-SceneId <uuid>] [-Environment prod|dev] [-DryRun]    # ✅ COMPLETE
Get-C3DObjects [-SceneId <uuid>] [-Environment prod|dev] [-OutputFile <path>] [-FormatAsManifest]    # ✅ COMPLETE

# Test-C3DUploads source exists at Public/Test-C3DUploads.ps1 but is intentionally
# unexported (still a placeholder that throws). Add to FunctionsToExport in
# C3DUploadTools.psd1 once a real implementation lands.

# Environment variable support - SceneId parameter is optional when C3D_SCENE_ID is set

PowerShell Advantages Over Bash

Feature Bash (current) PowerShell (new)
Dependencies Requires jq and curl No external dependencies
JSON Processing External jq command Native ConvertFrom-Json
HTTP Requests External curl command Native System.Net.WebClient (Windows compatible)
Error Handling Exit codes + manual parsing Rich exception objects with detailed context
Parameter Validation Manual validation functions Declarative [Parameter()] attributes
File Operations External commands (cp, mv) Native PowerShell cmdlets
Cross-platform Paths Manual path handling Automatic path normalization
Progress Indicators Basic text output Native progress bars for uploads
Windows Integration Limited Windows support Native Windows PowerShell support

Module Organization

C3DUploadTools/
├── Public/                    # User-facing functions (5 functions)
├── Private/                   # Internal functions organized by purpose
│   ├── Core/                 # Logging, error handling, classes, configuration
│   ├── Validation/           # API key, UUID, file system validation
│   ├── Api/                  # HTTP requests, multipart data, response handling
│   └── Utilities/            # Upload sessions, helper functions
└── Tests/                    # All test scripts (moved from root directory)
    ├── test-module-structure.ps1
    ├── test-utilities-internal.ps1
    ├── test-scene-upload.ps1
    ├── test-object-upload.ps1
    ├── test-core-utilities.ps1
    └── Test-EnvWorkflow.ps1

PowerShell Gallery Readiness

Status: 95% Ready for Publication

  • ✅ Enterprise-grade module structure and organization
  • ✅ Comprehensive parameter validation and error handling
  • ✅ Rich comment-based help with real-world examples
  • ✅ Cross-platform compatibility (Windows + Linux + macOS)
  • ✅ Professional documentation and best practices
  • 📋 Remaining: Pester test suite for automated testing

Enterprise-Grade Improvements Implemented

Code Quality & Architecture

  • Function refactoring: Split large 500+ line functions into focused, single-responsibility components
  • Type safety: PowerShell classes for structured request/response handling
  • Error handling: Consistent error records with proper categories and actionable guidance
  • Input validation: Comprehensive [ValidateScript()] blocks with UUID, file, and directory validation

User Experience

  • Progress indicators: Visual feedback for long-running upload operations
  • Detailed help: Real-world examples, complete workflows, and troubleshooting guidance
  • Clear error messages: Specific instructions for resolving common issues
  • Workflow automation: Environment variable support for streamlined batch operations

Performance & Reliability

  • Memory efficiency: Optimized file handling for large uploads without external dependencies
  • Cross-platform: Native Windows PowerShell and PowerShell Core compatibility
  • Security: Secure credential handling with no API key logging or exposure
  • Robustness: Automatic settings.json generation, retry logic, and comprehensive validation

Compatibility & Production Readiness

  • Bash Scripts: Continue to work as before (no breaking changes)
  • PowerShell Module: Enterprise-grade Windows compatibility with no external dependencies
  • Cross-platform: Tested on Windows PowerShell 5.1+, PowerShell Core 7.x, macOS, and Linux
  • Production-ready: All functions complete with comprehensive validation and error handling
  • Professional quality: Suitable for enterprise environments and PowerShell Gallery publication

PowerShell HTTP Client Implementation ✅

Challenge Resolved: PowerShell's Invoke-WebRequest validates Authorization headers strictly and rejects the APIKEY:DEVELOPER format required by Cognitive3D API.

Solution: Uses System.Net.WebClient for multipart uploads with manual multipart form data construction:

  • ✅ Windows Compatible: No external dependencies (curl, jq) required
  • ✅ Authorization Working: Custom APIKEY:DEVELOPER format bypasses PowerShell validation
  • ✅ Multipart Uploads: Manual boundary construction for object file uploads
  • ✅ Full Functionality: Object upload (HTTP 200) and manifest upload (HTTP 201) working
  • ✅ Environment Variables: C3D_SCENE_ID fallback fully functional
  • ✅ Cross-platform: Works on Windows PowerShell 5.1+ and PowerShell Core 7.x+