REFACTORING_CHECKLIST.md

SDK Refactoring Checklist

Use this checklist when refactoring a UN SDK to ensure nothing is missed.

Pre-Refactoring

• Read tests/AGENT_REFACTORING_INSTRUCTIONS.md
• Study Python SDK (un.py) as reference
• Study JavaScript SDK (un.js) as reference
• Create test file tests/test_un_{language}.{ext}
• Run baseline tests: python3 tests/test_sdk_library.py --languages {lang}

Core Library Functions

Execution Functions

• execute(language, code, opts) - Sync execution
• executeAsync(language, code, opts) - Async execution
• run(file, opts) - Run file sync
• runAsync(file, opts) - Run file async

Job Management

• wait(job_id, timeout) - Poll for completion
• getJob(job_id) - Get job status
• cancelJob(job_id) - Cancel running job
• listJobs(limit) - List active jobs

Snapshots (NEW!)

• sessionSnapshot(session_id) - Create session snapshot
• serviceSnapshot(service_id) - Create service snapshot
• listSnapshots() - List all snapshots
• restoreSnapshot(snapshot_id) - Restore from snapshot
• deleteSnapshot(snapshot_id) - Delete snapshot

Utilities

• languages(cache_ttl) - Get supported languages
• languageInfo(language) - Get language details
• detectLanguage(filename) - Detect from extension
• image(code, format) - Generate images

Credential System (4-tier)

• Load from function arguments (highest priority)
• Load from env vars: UNSANDBOX_PUBLIC_KEY + UNSANDBOX_SECRET_KEY
• Load from ~/.unsandbox/accounts.csv
• Load from ./accounts.csv (local directory)
• Raise error if no credentials found
• Test all 4 credential sources work

HMAC Signature

• Implement _sign_request(secret, timestamp, method, endpoint, body)
• Generate signature: HMAC-SHA256(secret, "{timestamp}:{method}:{endpoint}:{body}")
• Signature format: 64 lowercase hexadecimal characters
• Include headers in requests:
  • Authorization: Bearer {public_key}
  • X-Timestamp: {unix_timestamp}
  • X-Signature: {signature}
  • Content-Type: application/json
• Test signature generation produces correct format

Languages Cache

• Create cache directory: ~/.unsandbox/
• Cache location: ~/.unsandbox/languages.json
• Cache TTL: 3600 seconds (1 hour)
• Check cache exists AND is fresh before API call
• Only update cache on successful API response
• Create directory if needed before writing
• Test cache is used (don't call API twice within 1 hour)

Error Handling

Define exception classes:

• UnsandboxError - Base exception
• AuthenticationError - Invalid credentials
• ExecutionError - Code execution failed
• APIError - API communication error
• TimeoutError - Job polling timeout

Implement proper error handling:

• Handle network errors gracefully
• Handle invalid credentials
• Handle API errors (4xx, 5xx)
• Handle malformed responses
• Handle job timeout scenarios

Code Quality

Docstrings (Language-Appropriate)

• Python: """ """ triple quotes
• JavaScript: /** */ JSDoc format with @param @returns
• Go: // line comments before functions
• Ruby: # line comments before methods
• PHP: /** */ doc blocks
• Java: /** */ Javadoc format
• C/C++: // // or /* */ comments
• All public functions documented
• All parameters documented
• Return types documented
• Examples in docstrings

Code Style

• Follow language conventions
• Use language-idiomatic patterns
• Consistent naming (snake_case, camelCase, PascalCase as appropriate)
• Proper error handling throughout
• No hardcoded credentials
• No debugging print statements
• No commented-out code

License Header

• Full permacomputer public domain notice (35+ lines)
• Placed at very top of file
• Followed by blank line
• All license text preserved exactly

CLI Functionality

• Original CLI behavior preserved
• Can execute code files: un {file}
• Can execute inline code: un -s language 'code'
• Proper usage/help output
• Correct exit codes
• Error messages to stderr
• Output to stdout
• Support for all original flags/options

CLI Entry Point

• Python: if __name__ == '__main__':
• JavaScript: if (require.main === module):
• Go: Separate main() function
• Ruby: if __FILE__ == $0:
• Other languages: Language-appropriate

Testing

Unit Tests

• Create tests/test_un_{language}.{ext}
• Test credential loading (all 4 sources)
• Test HMAC signature generation
• Test function existence and signatures
• Test error handling for invalid inputs
• Tests pass: python3 tests/test_sdk_library.py --languages {lang}

Manual Testing

• Can import/require library: import un or require('./un')
• Can call each function without errors
• Credentials load correctly
• HMAC signatures generate correctly
• Cache is created and used
• CLI still works: un.py test.py or node un.js test.js

Integration Testing (if API key available)

• execute() works with real API
• executeAsync() works with real API
• wait() polls correctly
• Examples execute successfully

Documentation

Example Files

• Update unsandbox.com/priv/static/docs/examples/{language}/execute.txt
• Update unsandbox.com/priv/static/docs/examples/{language}/execute_async.txt
• Show library import/require
• Show credential setup (env vars)
• Show proper HMAC authentication
• Show error handling
• Code runs successfully

Comments in Code

• Explain complex logic
• Document public API
• Note any language-specific workarounds
• Explain credential priority system
• Explain cache invalidation

Git Workflow

• Create feature branch (optional): git checkout -b refactor/{language}
• Implement and test incrementally
• Commit with clear message explaining changes
• Include test file in commit
• Run all tests before committing
• Push to main (or PR if using branches)

Commit Message Template

Refactor {Language} SDK: add library exports + HMAC auth + caching

- Implement execute, executeAsync, wait, getJob, cancelJob, listJobs
- Add 4-tier credential system (args > env > home > local)
- Add 1-hour cache for languages list
- Implement HMAC-SHA256 request signing
- Preserve original CLI functionality
- Language-specific docstrings
- Full test coverage

Final Validation

Before declaring complete:

• git status is clean (all changes committed)
• Unit tests pass: python3 tests/test_sdk_library.py --languages {lang}
• Master test runner passes: ./tests/run_sdk_tests.sh --languages {lang}
• CLI still works: un.{ext} test.{ext}
• Library imports work: from un import execute or const un = require('./un')
• Examples in docs can be copied and executed
• No syntax errors in any files
• No hardcoded credentials
• No debug code or print statements
• Git history is clean and meaningful

Special Cases

Compiled Languages (C, Go, Rust, etc.)

• Build works without errors
• No build artifacts committed
• Can be run after compilation
• Tests include compilation step
• Documentation mentions compilation requirement

JVM Languages (Java, Kotlin, Scala, etc.)

• No .class or compiled files committed
• Build files present if needed
• Tests work with build system
• Documentation mentions build tool

Functional Languages (Haskell, OCaml, etc.)

• Pure functions for calculations
• Monads for I/O and side effects
• Tests use language-specific patterns
• Documentation explains functional patterns

Web Languages (PHP, JSP, etc.)

• Can run as CLI (not just web server)
• No web server dependency for CLI mode
• Tests work without web server

Estimated Language Groupings

Fast (< 2 hours)

• Ruby, Perl, PHP, Lua, TCL, Shell/Bash, Deno

Medium (2-4 hours)

• Go, TypeScript, Crystal, Dart, Elixir, Scala, Kotlin

Slower (4+ hours)

• Rust (borrow checker learning curve), C++, Java, Fortran, COBOL

Help & Resources

• AGENT_REFACTORING_INSTRUCTIONS.md - Detailed walkthrough
• SDK_TESTING_GUIDE.md - Testing patterns and examples
• un.py - Python reference implementation (canonical)
• un.js - JavaScript reference implementation
• tests/test_sdk_library.py - Python test framework
• tests/run_sdk_tests.sh - Master test runner
• tests/test_un_{lang}.{ext} - Language-specific test examples

Success = Complete Testing Pass

Your SDK refactoring is done when:

✓ 8/8 passed (0 failed)

All unit tests pass, no failures, all functions tested.