@seanmozeik/s3up 0.3.1

package/README.md

@@ -0,0 +1,204 @@
+# s3up
+
+Upload files to S3-compatible storage. Supports AWS S3, Cloudflare R2, DigitalOcean Spaces, Backblaze B2, and custom endpoints.
+
+## Features
+
+**Simple uploads** — Upload files with a single command. URLs copied to clipboard automatically.
+
+**Directory archiving** — Point at a directory, get a `.tar.gz` uploaded. Uses Bun's native Archive API.
+
+**Multipart uploads** — Files over 100MB are automatically uploaded in parallel chunks with resume support.
+
+**Lifecycle management** — List and prune old backups with `list` and `prune` commands.
+
+**Automation-ready** — Quiet mode (`--quiet`) and CI mode (`--ci`) for scripts and cron jobs.
+
+**Multiple providers** — AWS S3, Cloudflare R2, DigitalOcean Spaces, Backblaze B2, or any S3-compatible endpoint.
+
+**Fast** — Bun. Standalone binary. Native S3 client.
+
+```bash
+s3up image.png
+s3up ./workspace --prefix backups/daily
+s3up list backups/
+s3up prune backups/ --keep-last 7
+```
+
+## Install
+
+**Homebrew**
+
+```bash
+brew install seanmozeik/tap/s3up
+```
+
+**From source** (requires [Bun](https://bun.sh))
+
+```bash
+git clone https://github.com/mozeik/s3up.git
+cd s3up
+bun install
+bun run build
+```
+
+Produces a standalone binary. Move it to your PATH:
+
+```bash
+mv s3up ~/.local/bin/
+```
+
+## Setup
+
+Run `s3up setup` to configure credentials interactively:
+
+```bash
+s3up setup
+```
+
+Select your provider and enter credentials. Stored securely in system keychain.
+
+**Environment variable** — For containers/CI, set `S3UP_CONFIG` as JSON:
+
+```bash
+export S3UP_CONFIG='{
+  "provider": "r2",
+  "accessKeyId": "...",
+  "secretAccessKey": "...",
+  "bucket": "my-bucket",
+  "publicUrlBase": "https://cdn.example.com",
+  "accountId": "..."
+}'
+```
+
+## Usage
+
+### Upload
+
+```bash
+# Single file
+s3up image.png
+
+# Multiple files
+s3up *.png
+
+# Directory (auto-tarballed)
+s3up ./workspace
+
+# With prefix
+s3up backup.sql --prefix db/2026-01-31
+
+# Multiple directories into one tarball
+s3up ./workspace ./config --prefix backups
+
+# Custom tarball name
+s3up ./workspace --as full-backup.tar.gz
+```
+
+**Upload options:**
+
+```
+--prefix <path>       Prepend path to uploaded keys
+--as <name>           Override tarball filename for directories
+--compression <1-12>  Gzip compression level (default: 6)
+-f, --fast            Fast network preset (5MB chunks, 16 connections)
+-s, --slow            Slow network preset (50MB chunks, 4 connections)
+```
+
+### List
+
+```bash
+# List all objects
+s3up list
+
+# List with prefix
+s3up list backups/workspace/
+
+# JSON output
+s3up list backups/ --json
+```
+
+### Prune
+
+```bash
+# Keep last 7 backups
+s3up prune backups/workspace/ --keep-last 7
+
+# Delete objects older than 30 days
+s3up prune backups/ --older-than 30
+
+# Preview what would be deleted
+s3up prune backups/ --keep-last 7 --dry-run
+```
+
+**Prune options:**
+
+```
+--older-than <days>   Delete objects older than N days
+--keep-last <n>       Keep only N most recent objects
+--min-age <duration>  Minimum age before deletion (default: 1d)
+--dry-run             Show what would be deleted
+```
+
+**Safety:** Objects younger than `--min-age` (default 1 day) are never deleted, even if they match other criteria.
+
+### Global Options
+
+```
+-q, --quiet    Minimal output for scripting
+--ci           Non-interactive mode (fails if prompt required)
+-h, --help     Show help
+-v, --version  Show version
+```
+
+## Automation
+
+Example backup cron script:
+
+```bash
+#!/bin/bash
+set -e
+
+DATE=$(date +%Y-%m-%d)
+
+# Upload workspace directory
+s3up ./workspace --prefix "backups/workspace/${DATE}" --ci -q
+
+# Prune old backups (keep last 14)
+s3up prune "backups/workspace/" --keep-last 14 --ci -q
+
+echo "Backup complete: ${DATE}"
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Configuration error |
+| 3 | Interactive prompt required in --ci mode |
+| 4 | Partial failure (some files failed) |
+
+## Providers
+
+| Provider | Configuration |
+|----------|---------------|
+| AWS S3 | `provider: "aws"`, `region` required |
+| Cloudflare R2 | `provider: "r2"`, `accountId` required |
+| DigitalOcean Spaces | `provider: "digitalocean"`, `region` required |
+| Backblaze B2 | `provider: "backblaze"`, `region` required |
+| Custom | `provider: "custom"`, `endpoint` required |
+
+## Development
+
+```bash
+bun install
+bun run dev           # Run from source
+bun run build         # Build standalone binary
+bun test              # Run tests
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@seanmozeik/s3up",
+  "version": "0.3.1",
+  "description": "Upload files to S3-compatible storage",
+  "type": "module",
+  "bin": {
+    "s3up": "src/index.ts"
+  },
+  "files": [
+    "src",
+    "package.json"
+  ],
+  "keywords": [
+    "s3",
+    "upload",
+    "cli",
+    "bun",
+    "r2",
+    "cloudflare",
+    "aws",
+    "backblaze"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seanmozeik/s3up.git"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.0.0",
+    "boxen": "^8.0.1",
+    "figlet": "^1.10.0",
+    "gradient-string": "^3.0.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.13",
+    "@types/bun": "1.3.8",
+    "@types/figlet": "^1.7.0",
+    "@types/gradient-string": "^1.1.6",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --compile --outfile s3up --minify",
+    "bundle": "bun build ./src/index.ts --outdir dist --target=bun --bytecode --minify",
+    "check": "biome check --write --unsafe .",
+    "dev": "bun run src/index.ts",
+    "format": "biome format --write .",
+    "install-local": "bun run build && mkdir -p ~/.local/bin && mv s3up ~/.local/bin/s3up && chmod +x ~/.local/bin/s3up",
+    "tc": "tsc --noEmit",
+    "test": "bun test"
+  }
+}

package/src/commands/list.test.ts

@@ -0,0 +1,31 @@
+// src/commands/list.test.ts
+import { describe, expect, test } from 'bun:test';
+import { formatListOutput } from './list';
+
+describe('formatListOutput', () => {
+  const objects = [
+    {
+      key: 'backups/file1.tar.gz',
+      lastModified: new Date('2026-01-28T10:00:00Z'),
+      size: 1024000
+    },
+    {
+      key: 'backups/file2.tar.gz',
+      lastModified: new Date('2026-01-29T10:00:00Z'),
+      size: 2048000
+    }
+  ];
+
+  test('formats as tab-separated in quiet mode', () => {
+    const result = formatListOutput(objects, true, false);
+    expect(result).toContain('backups/file1.tar.gz');
+    expect(result).toContain('\t');
+  });
+
+  test('formats as JSON with --json flag', () => {
+    const result = formatListOutput(objects, true, true);
+    const lines = result.trim().split('\n');
+    expect(lines).toHaveLength(2);
+    expect(JSON.parse(lines[0]).key).toBe('backups/file1.tar.gz');
+  });
+});

package/src/commands/list.ts

@@ -0,0 +1,58 @@
+// src/commands/list.ts
+import * as p from '@clack/prompts';
+
+import { type GlobalFlags, parseListFlags } from '../lib/flags';
+import { formatBytes, formatListItem } from '../lib/output';
+import { loadConfig } from '../lib/providers';
+import { createS3Client, listAllObjects, type S3Object } from '../lib/s3';
+import { showBanner } from '../ui/banner';
+import { frappe } from '../ui/theme';
+
+export function formatListOutput(objects: S3Object[], quiet: boolean, json: boolean): string {
+  return objects.map((o) => formatListItem(o.key, o.size, o.lastModified, quiet, json)).join('\n');
+}
+
+export async function list(args: string[], globalFlags: GlobalFlags): Promise<void> {
+  const flags = parseListFlags(args);
+
+  const config = await loadConfig();
+  if (!config) {
+    if (globalFlags.ci) {
+      console.error('Error: S3UP_CONFIG not set and --ci prevents interactive setup');
+      process.exit(2);
+    }
+    if (!globalFlags.quiet) await showBanner();
+    p.log.error('S3 not configured. Run: s3up setup');
+    process.exit(2);
+  }
+
+  if (!globalFlags.quiet) {
+    await showBanner();
+    p.intro(frappe.text(`Listing objects${flags.prefix ? ` with prefix: ${flags.prefix}` : ''}`));
+  }
+
+  const client = createS3Client(config);
+  const objects = await listAllObjects(client, flags.prefix);
+
+  if (objects.length === 0) {
+    if (globalFlags.quiet) {
+      // No output for empty results in quiet mode
+    } else {
+      p.log.info('No objects found');
+    }
+    process.exit(0);
+  }
+
+  // Sort by lastModified descending (newest first)
+  objects.sort((a, b) => b.lastModified.getTime() - a.lastModified.getTime());
+
+  const output = formatListOutput(objects, globalFlags.quiet, flags.json);
+  console.log(output);
+
+  if (!globalFlags.quiet) {
+    const totalSize = objects.reduce((sum, o) => sum + o.size, 0);
+    p.outro(frappe.subtext1(`${objects.length} objects (${formatBytes(totalSize)} total)`));
+  }
+
+  process.exit(0);
+}

package/src/commands/prune.test.ts

@@ -0,0 +1,83 @@
+// src/commands/prune.test.ts
+import { describe, expect, test } from 'bun:test';
+import type { S3Object } from '../lib/s3';
+import { filterObjectsForPrune } from './prune';
+
+describe('filterObjectsForPrune', () => {
+  const now = new Date('2026-01-31T12:00:00Z').getTime();
+
+  const objects: S3Object[] = [
+    {
+      key: 'backups/file1.tar.gz',
+      lastModified: new Date('2026-01-30T12:00:00Z'),
+      size: 1000
+    }, // 1 day old
+    {
+      key: 'backups/file2.tar.gz',
+      lastModified: new Date('2026-01-29T12:00:00Z'),
+      size: 2000
+    }, // 2 days old
+    {
+      key: 'backups/file3.tar.gz',
+      lastModified: new Date('2026-01-28T12:00:00Z'),
+      size: 3000
+    }, // 3 days old
+    {
+      key: 'backups/file4.tar.gz',
+      lastModified: new Date('2026-01-20T12:00:00Z'),
+      size: 4000
+    }, // 11 days old
+    {
+      key: 'backups/file5.tar.gz',
+      lastModified: new Date('2026-01-10T12:00:00Z'),
+      size: 5000
+    } // 21 days old
+  ];
+
+  test('filters by --older-than', () => {
+    const result = filterObjectsForPrune(objects, {
+      minAge: '0',
+      now,
+      olderThan: 10
+    });
+    expect(result.map((o) => o.key)).toEqual(['backups/file4.tar.gz', 'backups/file5.tar.gz']);
+  });
+
+  test('filters by --keep-last', () => {
+    const result = filterObjectsForPrune(objects, {
+      keepLast: 2,
+      minAge: '0',
+      now
+    });
+    // Keeps 2 newest, deletes rest
+    expect(result.map((o) => o.key)).toEqual([
+      'backups/file3.tar.gz',
+      'backups/file4.tar.gz',
+      'backups/file5.tar.gz'
+    ]);
+  });
+
+  test('respects --min-age default (1d)', () => {
+    const result = filterObjectsForPrune(objects, {
+      keepLast: 1,
+      minAge: '1d',
+      now
+    });
+    // file1 is only 1 day old, protected by min-age
+    expect(result.map((o) => o.key)).not.toContain('backups/file1.tar.gz');
+  });
+
+  test('combines --older-than and --keep-last (both must match)', () => {
+    const result = filterObjectsForPrune(objects, {
+      keepLast: 3,
+      minAge: '0',
+      now,
+      olderThan: 2
+    });
+    // Must be older than 2 days AND not in top 3
+    // Top 3: file1, file2, file3
+    // Older than 2 days: file3, file4, file5
+    // Both: file4, file5
+    expect(result.map((o) => o.key)).toEqual(['backups/file4.tar.gz', 'backups/file5.tar.gz']);
+  });
+});

package/src/commands/prune.ts

@@ -0,0 +1,159 @@
+// src/commands/prune.ts
+import * as p from '@clack/prompts';
+
+import { type GlobalFlags, parsePruneFlags } from '../lib/flags';
+import { formatBytes, formatDeleteSummary, formatDryRunList } from '../lib/output';
+import { loadConfig } from '../lib/providers';
+import { createS3Client, deleteObjects, listAllObjects, parseAge, type S3Object } from '../lib/s3';
+import { showBanner } from '../ui/banner';
+import { frappe, theme } from '../ui/theme';
+
+export interface PruneFilterOptions {
+  olderThan?: number;
+  keepLast?: number;
+  minAge: string;
+  now?: number;
+}
+
+export function filterObjectsForPrune(
+  objects: S3Object[],
+  options: PruneFilterOptions
+): S3Object[] {
+  const now = options.now ?? Date.now();
+  const minAgeMs = parseAge(options.minAge);
+
+  // Sort by lastModified descending (newest first)
+  const sorted = [...objects].sort((a, b) => b.lastModified.getTime() - a.lastModified.getTime());
+
+  // Build set of protected keys (top N newest)
+  const protectedKeys = new Set<string>();
+  if (options.keepLast) {
+    for (let i = 0; i < Math.min(options.keepLast, sorted.length); i++) {
+      protectedKeys.add(sorted[i].key);
+    }
+  }
+
+  return sorted.filter((obj) => {
+    const age = now - obj.lastModified.getTime();
+
+    // Must be older than min-age
+    if (age <= minAgeMs) return false;
+
+    // Must not be in protected set (keep-last)
+    if (protectedKeys.has(obj.key)) return false;
+
+    // Must be older than --older-than days
+    if (options.olderThan !== undefined) {
+      const olderThanMs = options.olderThan * 24 * 60 * 60 * 1000;
+      if (age <= olderThanMs) return false;
+    }
+
+    return true;
+  });
+}
+
+export async function prune(args: string[], globalFlags: GlobalFlags): Promise<void> {
+  const flags = parsePruneFlags(args);
+
+  // Validate required prefix
+  if (!flags.prefix) {
+    console.error('Error: prefix is required for prune command');
+    console.error('Usage: s3up prune <prefix> --keep-last <n> | --older-than <days>');
+    process.exit(1);
+  }
+
+  // Validate at least one filter
+  if (flags.olderThan === undefined && flags.keepLast === undefined) {
+    console.error('Error: at least one of --older-than or --keep-last is required');
+    process.exit(1);
+  }
+
+  const config = await loadConfig();
+  if (!config) {
+    if (globalFlags.ci) {
+      console.error('Error: S3UP_CONFIG not set and --ci prevents interactive setup');
+      process.exit(2);
+    }
+    if (!globalFlags.quiet) await showBanner();
+    p.log.error('S3 not configured. Run: s3up setup');
+    process.exit(2);
+  }
+
+  if (!globalFlags.quiet) {
+    await showBanner();
+    p.intro(frappe.text(`Pruning objects with prefix: ${flags.prefix}`));
+  }
+
+  const client = createS3Client(config);
+  const objects = await listAllObjects(client, flags.prefix);
+
+  if (objects.length === 0) {
+    if (globalFlags.quiet) {
+      console.log('0 objects deleted');
+    } else {
+      p.log.info('No objects found matching prefix');
+    }
+    process.exit(0);
+  }
+
+  const toDelete = filterObjectsForPrune(objects, {
+    keepLast: flags.keepLast,
+    minAge: flags.minAge,
+    olderThan: flags.olderThan
+  });
+
+  if (toDelete.length === 0) {
+    if (globalFlags.quiet) {
+      console.log('0 objects deleted');
+    } else {
+      p.log.info('No objects match deletion criteria');
+    }
+    process.exit(0);
+  }
+
+  const totalSize = toDelete.reduce((sum, o) => sum + o.size, 0);
+
+  // Dry run mode
+  if (flags.dryRun) {
+    console.log(formatDeleteSummary(toDelete.length, totalSize, true, globalFlags.quiet));
+    if (!globalFlags.quiet) {
+      console.log(formatDryRunList(toDelete));
+    }
+    process.exit(0);
+  }
+
+  // Confirm deletion in interactive mode
+  if (!globalFlags.ci && !globalFlags.quiet) {
+    console.log(formatDryRunList(toDelete));
+    const confirm = await p.confirm({
+      message: `Delete ${toDelete.length} objects (${formatBytes(totalSize)})?`
+    });
+
+    if (p.isCancel(confirm) || !confirm) {
+      p.outro(frappe.subtext1('Cancelled'));
+      process.exit(0);
+    }
+  }
+
+  // Perform deletion
+  const spinner = globalFlags.quiet ? undefined : p.spinner();
+  spinner?.start(`Deleting ${toDelete.length} objects...`);
+
+  const { deleted, errors } = await deleteObjects(
+    client,
+    toDelete.map((o) => o.key)
+  );
+
+  if (errors.length > 0) {
+    spinner?.stop(theme.warning(`Deleted ${deleted}/${toDelete.length} objects`));
+    for (const err of errors) {
+      console.error(`Error: ${err}`);
+    }
+    process.exit(4);
+  }
+
+  spinner?.stop(theme.success(`Deleted ${deleted} objects`));
+  console.log(formatDeleteSummary(deleted, totalSize, false, globalFlags.quiet));
+
+  process.exit(0);
+}