Feat: Support S3/R2 storage backends in perstack log command

[FL4TLiN3]

Description

The perstack log command currently only supports FileSystemStorage. Users who store their Perstack data in S3 or R2 cannot use the log command to inspect their execution history.

Use Case

• Production deployments often use cloud storage (S3/R2) for durability and scalability
• Users need to debug and inspect execution history stored in cloud backends
• AI agents need a unified way to access logs regardless of storage backend

Current State

• log.ts hardcodes FileSystemStorage
• createStorageAdapter uses filesystem-specific operations (existsSync, readdirSync, statSync)
• perstack.toml has no storage configuration field
• S3/R2 storage packages exist (@perstack/s3-storage, @perstack/r2-storage) but cannot be used with log command

Proposed Solution

1. Add storage configuration to perstack.toml

[storage]
type = "s3"  # "filesystem" | "s3" | "r2"

[storage.s3]
bucket = "my-perstack-bucket"
region = "us-east-1"
prefix = "perstack/"

2. Extend Storage interface

Add to Storage interface:

• listJobIds(): Promise<string[]> - List all job IDs (for fallback when job.json is missing)
• getStorageInfo(): StorageInfo - Get storage metadata for display

3. Create Storage Factory

Dynamic import-based factory to avoid bundling unused SDKs:

async function createStorageFromConfig(config: PerstackConfig): Promise<Storage>

4. Update log command

• Remove hardcoded FileSystemStorage
• Load storage configuration from perstack.toml
• Remove filesystem-specific code from createStorageAdapter

Implementation Phases

Phase	Work	Estimate
Phase 1	Add listJobIds() and getStorageInfo() to Storage interface and implementations	2-3h
Phase 2	Add storage configuration to perstack.toml schema	1h
Phase 3	Create createStorageFromConfig factory	1-2h
Phase 4	Update log.ts and data-fetcher.ts to be storage-agnostic	2-3h
Phase 5	Tests (Unit + E2E), documentation	2-3h

Acceptance Criteria

• perstack log works with FileSystemStorage (no regression)
• perstack log works with S3Storage when configured
• perstack log works with R2Storage when configured
• Storage type is displayed in log output
• perstack.toml schema validates storage configuration
• Documentation updated with storage configuration examples
• Unit tests for storage factory
• E2E tests verify log command with different storage types (mocked)

Related

• Depends on existing storage packages: @perstack/s3-storage, @perstack/r2-storage, @perstack/filesystem-storage
• Related to Feat: perstack log command #183 (add log command)

[github-actions]

🤖 Processing...

---