Skip to content

Comments

Replace UUID with shortuuid for session IDs#404

Merged
nikblanchet merged 9 commits intomainfrom
shortuuid-session-ids
Nov 28, 2025
Merged

Replace UUID with shortuuid for session IDs#404
nikblanchet merged 9 commits intomainfrom
shortuuid-session-ids

Conversation

@nikblanchet
Copy link
Owner

@nikblanchet nikblanchet commented Nov 28, 2025 •
edited
Loading

Summary

  • Replace 36-character UUIDs with 22-character shortuuids for session and transaction IDs
  • Port Python shortuuid implementation to TypeScript for cross-language consistency
  • Display shortuuids with hyphens every 4 chars from right for readability (e.g., vytx-eTZs)
  • Accept both UUID and shortuuid formats indefinitely for backward compatibility

Changes

Core modules:

  • analyzer/src/utils/shortuuid.py - Python implementation (generate, encode, decode, format_display, is_valid)
  • cli/src/utils/shortuuid.ts - TypeScript port with matching API
  • test-fixtures/shortuuid-vectors.json - Cross-language test vectors

Validation:

  • cli/src/utils/validation.ts - New isValidShortUuid, isValidSessionId, formatSessionIdForDisplay
  • cli/src/types/session-id.ts - Zod schema accepting both formats
  • Session state schemas updated to use SessionIdSchema

Generation switched:

  • cli/src/commands/audit.ts
  • cli/src/session/interactive-session.ts

Display formatting (19 points updated):

  • cli/src/session/interactive-session.ts
  • cli/src/commands/audit-sessions.ts
  • cli/src/commands/improve-sessions.ts
  • cli/src/commands/audit.ts
  • cli/src/commands/improve.ts

Test plan

  • Python shortuuid tests (21 tests)
  • TypeScript shortuuid tests (23 tests)
  • Cross-language test vectors ensure Python/TS implementations match
  • All existing tests updated and passing (993 tests)
  • Manual verification of display formatting

Generated with Claude Code
Steered and verified by @nikblanchet (Ten Forward regular)

nikblanchet and others added 9 commits November 28, 2025 12:50
@nikblanchet @claude
Add shortuuid core modules for Python and TypeScript
2e5ba83 
Implements base57 encoding that produces 22-character session IDs instead of
36-character UUIDs. Uses BigInt in TypeScript and native int in Python for
cross-language compatibility.

Key functions: generate(), encode(), decode(), formatDisplay(), isValid()

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@nikblanchet @claude
Add shortuuid tests and shared test vectors
1690420 
Cross-language test vectors ensure Python and TypeScript implementations
produce identical output. Tests cover encode/decode roundtrip, display
formatting, validation, and edge cases.

- test-fixtures/shortuuid-vectors.json: Shared test vectors
- analyzer/tests/test_shortuuid.py: 21 Python tests
- cli/src/__tests__/utils/shortuuid.test.ts: 23 TypeScript tests

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@nikblanchet
Add session ID validation supporting both UUID and shortuuid formats
a68edfe 
- validation.ts: Add isValidShortUuid, isValidSessionId, detectSessionIdFormat
- session-id.ts: New SessionIdSchema Zod type accepting both formats
- audit-session-state.ts: Use SessionIdSchema for session_id
- improve-session-state.ts: Use SessionIdSchema for session_id, transaction_id

Backward compatible: existing UUID sessions continue to work.

Generated with [Claude Code](https://claude.com/claude-code)
Steered and verified by @nikblanchet
@nikblanchet
Update Python validate_session_id to accept both UUID and shortuuid
aebb42e 
Adds shortuuid validation alongside existing UUID validation.
Both formats accepted indefinitely for backward compatibility.

Generated with [Claude Code](https://claude.com/claude-code)
Steered and verified by @nikblanchet
@nikblanchet
Switch session ID generation to shortuuid
2968564 
- audit.ts: Use generate() from shortuuid instead of randomUUID()
- interactive-session.ts: Use generate() instead of uuidv4()

New sessions now use 22-character shortuuids. Existing UUID sessions
remain valid due to the updated validation accepting both formats.

Generated with [Claude Code](https://claude.com/claude-code)
Steered and verified by @nikblanchet
@nikblanchet
Add formatSessionIdForDisplay helper for hybrid UUID/shortuuid display
fc9326a 
Intelligently formats session IDs based on type:
- Shortuuids: truncates and adds hyphens every 4 chars (e.g., vytx-eTZs)
- UUIDs: simple truncation (they already have natural hyphen structure)

This helper can be used across display points for consistent formatting.

Generated with [Claude Code](https://claude.com/claude-code)
Steered and verified by @nikblanchet
@nikblanchet
Update session ID display to use formatSessionIdForDisplay helper
267300f 
Changes all session ID display points from raw .slice() to
formatSessionIdForDisplay(), which handles hybrid UUID/shortuuid
display correctly:

- Shortuuids: Truncated with hyphens every 4 chars (e.g., "vytx-eTZs")
- UUIDs: Simple truncation (already have natural hyphen structure)

Also updates validation from isValidUuid() to isValidSessionId()
which accepts both UUID and shortuuid formats.

Files modified:
- cli/src/session/interactive-session.ts
- cli/src/commands/audit-sessions.ts
- cli/src/commands/improve-sessions.ts
- cli/src/commands/audit.ts
- cli/src/commands/improve.ts

Test updates:
- InteractiveSession.test.ts: Updated regex to match shortuuid format
- audit-sessions.test.ts, improve-sessions.test.ts: Updated error message

Generated with [Claude Code](https://claude.com/claude-code)

Steered and verified by @nikblanchet
@nikblanchet
Fix lint errors in shortuuid implementation
0b1a7b3 
Python (ruff):
- Break long lines in encode() and test vectors fixture
- Use list.extend() instead of for loop with append in format_display()
- Shorten assertion message in test

TypeScript (eslint):
- Remove empty lines between import groups in type files
- Rename abbreviated variables (alphaLen -> alphabetLength, num -> value)
- Use String#replaceAll() instead of String#replace() with regex
- Fix JSDoc indentation

Generated with [Claude Code](https://claude.com/claude-code)

Steered and verified by @nikblanchet
@nikblanchet
Fix code formatting (ruff format, prettier)
5dcbf84 
Reformatted files to pass CI checks:
- analyzer/tests/test_shortuuid.py (ruff format)
- cli/src/commands/audit-sessions.ts (prettier)
- cli/src/commands/improve-sessions.ts (prettier)

Generated with [Claude Code](https://claude.com/claude-code)

Steered and verified by @nikblanchet
@nikblanchet nikblanchet merged commit 847502e into main Nov 28, 2025
5 checks passed
nikblanchet added a commit that referenced this pull request Nov 28, 2025
@nikblanchet
Add validation utility tests and truncate parameter validation
283a10b 
- Add comprehensive tests for 5 validation functions:
  - isValidShortUuid(): valid/invalid shortuuids, hyphenated input
  - isValidSessionId(): UUID, shortuuid, and hybrid validation
  - detectSessionIdFormat(): format detection tests
  - normalizeSessionId(): UUID preservation, hyphen stripping
  - formatSessionIdForDisplay(): truncation and hyphen formatting

- Add truncate parameter validation in formatDisplay():
  - Throws if truncate is negative or not an integer
  - Protects against invalid input values

- Add BigInt edge case comment explaining 0n behavior

Addresses post-merge review findings from PR #404.

Generated with [Claude Code](https://claude.com/claude-code)
Steered and verified by @nikblanchet
@nikblanchet nikblanchet mentioned this pull request Nov 28, 2025
Merged
6 tasks
nikblanchet added a commit that referenced this pull request Nov 28, 2025
@nikblanchet
Add validation utility tests and truncate parameter validation
7768756 
- Add comprehensive tests for 5 validation functions:
  - isValidShortUuid(): valid/invalid shortuuids, hyphenated input
  - isValidSessionId(): UUID, shortuuid, and hybrid validation
  - detectSessionIdFormat(): format detection tests
  - normalizeSessionId(): UUID preservation, hyphen stripping
  - formatSessionIdForDisplay(): truncation and hyphen formatting

- Add truncate parameter validation in formatDisplay():
  - Throws if truncate is negative or not an integer
  - Protects against invalid input values

- Add BigInt edge case comment explaining 0n behavior

Addresses post-merge review findings from PR #404.

Generated with [Claude Code](https://claude.com/claude-code)
Steered and verified by @nikblanchet
nikblanchet added a commit that referenced this pull request Nov 28, 2025
@nikblanchet
Add validation utility tests and truncate parameter validation (#406)
46ab56b 
* Add validation utility tests and truncate parameter validation

- Add comprehensive tests for 5 validation functions:
  - isValidShortUuid(): valid/invalid shortuuids, hyphenated input
  - isValidSessionId(): UUID, shortuuid, and hybrid validation
  - detectSessionIdFormat(): format detection tests
  - normalizeSessionId(): UUID preservation, hyphen stripping
  - formatSessionIdForDisplay(): truncation and hyphen formatting

- Add truncate parameter validation in formatDisplay():
  - Throws if truncate is negative or not an integer
  - Protects against invalid input values

- Add BigInt edge case comment explaining 0n behavior

Addresses post-merge review findings from PR #404.

Generated with [Claude Code](https://claude.com/claude-code)
Steered and verified by @nikblanchet

* Add code review enhancements for truncate validation

- Add truncate validation error tests (negative, non-integer, NaN, Infinity)
- Add truncate edge case tests (0 returns empty, large value returns full)
- Extract magic numbers to constants (ZERO_UUID_ENCODING, BASE57_EXCLUDED_CHARS)
- Add JSDoc example for truncate >= 22 (full formatted output)

Addresses code review findings from PR #406 first review.

Generated with [Claude Code](https://claude.com/claude-code)
Steered and verified by @nikblanchet
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@nikblanchet