feat(state): add encodeCursor/decodeCursor for pagination

[galligan]

URL-safe base64 encoding (RFC 4648 Section 5) for opaque cursor tokens.
Handles encoding/decoding of pagination state for API responses.

Closes #47

Co-Authored-By: Claude Opus 4.5 noreply@anthropic.com

[galligan]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• chore(outfitter): sync templates on pack #108
• chore(changesets): ignore app package #107
• fix(errors): avoid TaggedError extends warnings #106
• chore(release): align package versions to 0.1.0 #105
• docs: add README and CHANGELOG for testing, kit, outfitter #95
• feat(templates): add daemon project template #94
• feat(templates): add MCP server project template #93
• feat(templates): add CLI project template #92
• fix(cli): implement confirmDestructive prompts #104
• fix(cli): implement createCLI and command builder #103
• feat(kit): add @outfitter/kit meta-package #91
• docs(daemon): add README and CHANGELOG #90
• fix(daemon): fix locking module bugs (GREEN phase) #89
• test(daemon): add locking module tests (RED phase) #88
• feat(daemon): add errors, platform, and locking module stubs #87
• feat(outfitter): add doctor command for environment validation #86
• feat(outfitter): add init command with project scaffolding #85
• feat(daemon): add IPC communication and health checks #84
• feat(daemon): add types and lifecycle management #83
• feat(index): add FTS5 full-text search implementation #82
• feat(index): add types for FTS5 full-text search #81
• feat(testing): add MCP and CLI test harnesses #80
• feat(testing): add test fixture utilities #79
• feat(mcp): add MCP server implementation with typed handlers #78
• feat(mcp): add types and interfaces for MCP server #77
• feat(ui): add Shape discriminated union and render() #76
• feat(ui): add createTokens semantic color layer #75
• feat(state): add pagination helpers #74
• feat(logging): add DEFAULT_PATTERNS for common secret redaction #73
• feat(ui): add formatRelative() for human-readable timestamps #72
• feat(state): add encodeCursor/decodeCursor for pagination #71 👈 (View in Graphite)
• feat(types): add hashId() for deterministic short identifiers #70
• feat(contracts): add Logger.child() and fix AssertionError category #69
• feat(config): centralize environment variable access with Zod validation #42
• fix(logging): enable redaction by default when global rules exist #41
• docs(ui): add README, CHANGELOG, and TSDoc comments #39
• docs(state): add README, CHANGELOG, and TSDoc comments #38
• docs(file-ops): add README, CHANGELOG, and TSDoc comments #37
• docs(logging): add README, CHANGELOG, and TSDoc comments #36
• docs(config): add README, CHANGELOG, and TSDoc comments #35
• fix(cli): enforce cursor TTL #114
• fix(tests): remove placeholder tests #113
• chore(gitattributes): prefer ours for bun lockfiles #115
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 53afbd2a01

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[greptile-apps]

Greptile Summary

• Implements URL-safe base64 cursor encoding/decoding for opaque pagination tokens in API responses
• Adds comprehensive validation for decoded cursors including type checking, range validation, and field constraints
• Includes extensive test coverage following TDD principles with error handling and round-trip validation

Important Files Changed

Filename	Overview
packages/state/src/index.ts	Added encodeCursor() and decodeCursor() functions with URL-safe base64 implementation and comprehensive validation
packages/state/src/__tests__/state.test.ts	Added complete test coverage for cursor encoding functionality with round-trip and error handling tests

Confidence score: 5/5

• This PR is safe to merge with minimal risk and follows established patterns
• Score reflects well-tested implementation with comprehensive error handling and adherence to TDD methodology
• No files require special attention as both implementation and tests are thorough and consistent

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as "CLI Application"
    participant Store as "CursorStore"
    participant Encoder as "encodeCursor/decodeCursor"
    
    User->>CLI: "Request paginated data"
    CLI->>Store: "createCursor({position: 0})"
    Store-->>CLI: "Result<Cursor>"
    CLI->>Encoder: "encodeCursor(cursor)"
    Encoder-->>CLI: "URL-safe base64 token"
    CLI-->>User: "Return data + encoded cursor token"
    
    User->>CLI: "Request next page with cursor token"
    CLI->>Encoder: "decodeCursor(token)"
    Encoder-->>CLI: "Result<Cursor>"
    CLI->>Store: "advanceCursor(cursor, newPosition)"
    Store-->>CLI: "New Cursor"
    CLI->>Store: "set(advancedCursor)"
    CLI->>Encoder: "encodeCursor(advancedCursor)"
    Encoder-->>CLI: "New URL-safe base64 token"
    CLI-->>User: "Return next page + new cursor token"

Loading

[greptile-apps]

_{2 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[galligan]

Added coverage to reject negative cursor positions when decoding encoded cursors.

[galligan]

Replaced Buffer-based base64 in cursor encode/decode and tests with TextEncoder + btoa/atob helpers, and kept the negative-position validation in decodeCursor.

[galligan]

Resolved the Greptile Buffer/base64 feedback (already switched to TextEncoder + btoa/atob) and resubmitted after downstack updates.