s3-storage-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muneeb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# s3-storage-cli
+
+Minimal Bun CLI for tracked S3 uploads.
+
+Install:
+
+```bash
+npm install -g s3-storage-cli
+```
+
+Runtime requirement:
+
+- `bun` must be installed because the published CLI executes with Bun
+
+Commands:
+
+- `status` verifies env, SQLite, and S3 connectivity
+- `list` shows only objects tracked by this CLI
+- `upload` uploads one or more files or directories
+- `delete` removes tracked objects
+- `share` returns a direct public URL or a signed private URL
+
+Required env:
+
+- `S3_ENDPOINT`
+- `S3_REGION`
+- `S3_ACCESS_KEY_ID`
+- `S3_SECRET_ACCESS_KEY`
+- `S3_BUCKET`
+
+Required for full readiness and public sharing:
+
+- `S3_PUBLIC_BASE_URL`
+
+Optional env:
+
+- `S3_CLI_DB_PATH`
+- `S3_SHARE_TTL_SECONDS`
+- `S3_SESSION_TOKEN`
+- `S3_VIRTUAL_HOSTED_STYLE`
+
+Run:
+
+```bash
+bun run index.ts status
+```
+
+After global install:
+
+```bash
+s3-storage status
+```
+
+Examples:
+
+```bash
+bun run index.ts upload ./file.txt
+bun run index.ts upload ./assets --public --prefix site
+bun run index.ts list
+bun run index.ts share site/assets/logo.png
+bun run index.ts delete site/assets/logo.png
+```

package/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: s3-storage-cli
+description: Use this skill when you need to manage tracked uploads in this repository's S3 CLI. It covers status checks, tracked listing, uploads, deletes, and sharing links with token-efficient output.
+---
+
+# S3 Storage CLI
+
+Use this repo's CLI when the task is uploading files to the configured S3-compatible bucket, listing only files previously uploaded through this CLI, deleting tracked files, checking readiness, or generating share links.
+
+## Required env
+
+- `S3_ENDPOINT`
+- `S3_REGION`
+- `S3_ACCESS_KEY_ID`
+- `S3_SECRET_ACCESS_KEY`
+- `S3_BUCKET`
+
+`S3_PUBLIC_BASE_URL` is required for `status` to report fully ready and for public object sharing.
+
+Optional env:
+
+- `S3_CLI_DB_PATH`
+- `S3_SHARE_TTL_SECONDS`
+- `S3_SESSION_TOKEN`
+- `S3_VIRTUAL_HOSTED_STYLE`
+
+## Commands
+
+- `bun run index.ts status`
+- `bun run index.ts list [prefix]`
+- `bun run index.ts upload <paths...> [--public|--private] [--prefix <remote-prefix>]`
+- `bun run index.ts delete <keys...>`
+- `bun run index.ts share <key> [--expires <seconds>]`
+
+Short aliases are available: `ls`, `up`, `rm`, `sh`, `st`.
+
+## Behavior
+
+- `list` reads the local SQLite catalog only. It does not list the whole bucket.
+- `delete` only deletes tracked keys that are still active in the catalog.
+- `upload` preserves relative paths for directory uploads. Single-file uploads use the file basename.
+- `share` returns a direct URL for tracked public objects and a presigned URL for tracked private objects.
+- Default output is compact plain text. Add `--json` for machine-readable output.
+
+## Output contract
+
+- Success output is terse and stable.
+- Errors are one-line stderr records in the form `error<TAB>code<TAB>message`.
+- `share` plain output is the URL only.

package/index.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+
+import { runCli } from "./src/cli";
+
+const exitCode = await runCli(process.argv.slice(2));
+process.exit(exitCode);

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "s3-storage-cli",
+  "version": "0.1.0",
+  "description": "Minimal tracked S3 CLI for Bun with list, upload, delete, share, and status commands.",
+  "module": "index.ts",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "s3-storage": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src/catalog.ts",
+    "src/cli.ts",
+    "src/config.ts",
+    "src/files.ts",
+    "src/output.ts",
+    "src/storage.ts",
+    "README.md",
+    "SKILL.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "bun run index.ts",
+    "test": "bun test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/muneebhashone/s3-storage-cli.git"
+  },
+  "homepage": "https://github.com/muneebhashone/s3-storage-cli#readme",
+  "bugs": {
+    "url": "https://github.com/muneebhashone/s3-storage-cli/issues"
+  },
+  "keywords": [
+    "s3",
+    "cli",
+    "bun",
+    "sqlite",
+    "upload"
+  ],
+  "devDependencies": {
+    "@types/bun": "latest"
+  }
+}

package/src/catalog.ts

@@ -0,0 +1,164 @@
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { Database } from "bun:sqlite";
+import type { Visibility } from "./config";
+
+export interface CatalogRecord {
+  bucket: string;
+  contentType: string | null;
+  etag: string | null;
+  key: string;
+  size: number;
+  sourcePath: string;
+  uploadedAt: string;
+  visibility: Visibility;
+}
+
+export interface ListedObject {
+  contentType: string | null;
+  etag: string | null;
+  key: string;
+  size: number;
+  sourcePath: string;
+  uploadedAt: string;
+  visibility: Visibility;
+}
+
+export class Catalog {
+  private readonly db: Database;
+
+  constructor(databasePath: string) {
+    mkdirSync(dirname(databasePath), { recursive: true });
+    this.db = new Database(databasePath, { create: true, strict: true });
+    this.db.run("PRAGMA journal_mode = WAL;");
+    this.db.run("PRAGMA synchronous = NORMAL;");
+    this.init();
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  ping(): void {
+    this.db.query("SELECT 1 AS ok").get();
+  }
+
+  upsertObject(record: CatalogRecord): void {
+    this.db.run(
+      `
+        INSERT INTO objects (
+          bucket,
+          key,
+          visibility,
+          size,
+          etag,
+          content_type,
+          source_path,
+          uploaded_at,
+          deleted_at
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL)
+        ON CONFLICT(bucket, key)
+        DO UPDATE SET
+          visibility = excluded.visibility,
+          size = excluded.size,
+          etag = excluded.etag,
+          content_type = excluded.content_type,
+          source_path = excluded.source_path,
+          uploaded_at = excluded.uploaded_at,
+          deleted_at = NULL
+      `,
+      [
+        record.bucket,
+        record.key,
+        record.visibility,
+        record.size,
+        record.etag,
+        record.contentType,
+        record.sourcePath,
+        record.uploadedAt,
+      ],
+    );
+  }
+
+  listObjects(bucket: string, prefix?: string): ListedObject[] {
+    return this.db
+      .query<ListedObject, { bucket: string; prefix: string | null }>(
+        `
+          SELECT
+            key,
+            visibility,
+            size,
+            etag,
+            content_type AS contentType,
+            source_path AS sourcePath,
+            uploaded_at AS uploadedAt
+          FROM objects
+          WHERE bucket = $bucket
+            AND deleted_at IS NULL
+            AND ($prefix IS NULL OR key LIKE $prefix || '%')
+          ORDER BY key ASC
+        `,
+      )
+      .all({ bucket, prefix: prefix ?? null });
+  }
+
+  getObject(bucket: string, key: string): ListedObject | null {
+    return (
+      this.db
+        .query<ListedObject, { bucket: string; key: string }>(
+          `
+            SELECT
+              key,
+              visibility,
+              size,
+              etag,
+              content_type AS contentType,
+              source_path AS sourcePath,
+              uploaded_at AS uploadedAt
+            FROM objects
+            WHERE bucket = $bucket
+              AND key = $key
+              AND deleted_at IS NULL
+            LIMIT 1
+          `,
+        )
+        .get({ bucket, key }) ?? null
+    );
+  }
+
+  softDeleteObject(bucket: string, key: string, deletedAt: string): void {
+    this.db.run(
+      `
+        UPDATE objects
+        SET deleted_at = ?
+        WHERE bucket = ?
+          AND key = ?
+          AND deleted_at IS NULL
+      `,
+      [deletedAt, bucket, key],
+    );
+  }
+
+  private init(): void {
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS objects (
+        bucket TEXT NOT NULL,
+        key TEXT NOT NULL,
+        visibility TEXT NOT NULL CHECK (visibility IN ('private', 'public')),
+        size INTEGER NOT NULL,
+        etag TEXT,
+        content_type TEXT,
+        source_path TEXT NOT NULL,
+        uploaded_at TEXT NOT NULL,
+        deleted_at TEXT,
+        PRIMARY KEY (bucket, key)
+      )
+    `);
+
+    this.db.run(`
+      CREATE INDEX IF NOT EXISTS idx_objects_bucket_deleted_key
+      ON objects (bucket, deleted_at, key)
+    `);
+  }
+}

package/src/cli.ts

@@ -0,0 +1,523 @@
+import { dirname } from "node:path";
+import { mkdir } from "node:fs/promises";
+import { Catalog } from "./catalog";
+import {
+  ensurePublicBaseUrl,
+  getReadyEnvKeys,
+  inspectEnv,
+  requireCoreConfig,
+  resolveCatalogPath,
+  type AppConfig,
+  type EnvMap,
+  type Visibility,
+} from "./config";
+import { resolveUploadTargets } from "./files";
+import { createDefaultIo, emitEnvCheck, emitError, emitJson, formatTimestamp, type CliIo } from "./output";
+import { BunStorageClient, type StorageClient } from "./storage";
+
+interface ParsedArgs {
+  command: string | null;
+  flags: Record<string, string | boolean>;
+  positionals: string[];
+}
+
+interface RunCliOptions {
+  catalogPath?: string;
+  cwd?: string;
+  env?: EnvMap;
+  homeDir?: string;
+  io?: CliIo;
+  now?: () => Date;
+  storageFactory?: (config: AppConfig) => StorageClient;
+}
+
+interface StatusCheckResult {
+  message?: string;
+  name: string;
+  ok: boolean;
+}
+
+export async function runCli(argv: string[], options: RunCliOptions = {}): Promise<number> {
+  const io = options.io ?? createDefaultIo();
+  const env = options.env ?? process.env;
+  const cwd = options.cwd ?? process.cwd();
+  const now = options.now ?? (() => new Date());
+  const storageFactory = options.storageFactory ?? ((config: AppConfig) => new BunStorageClient(config));
+
+  try {
+    const parsed = parseArgs(argv);
+    if (!parsed.command || parsed.flags.help) {
+      printHelp(io);
+      return 0;
+    }
+
+    switch (parsed.command) {
+      case "list":
+      case "ls":
+        return await runList(parsed, { catalogPath: options.catalogPath, env, homeDir: options.homeDir, io });
+      case "upload":
+      case "up":
+        return await runUpload(parsed, {
+          catalogPath: options.catalogPath,
+          cwd,
+          env,
+          homeDir: options.homeDir,
+          io,
+          now,
+          storageFactory,
+        });
+      case "delete":
+      case "rm":
+        return await runDelete(parsed, {
+          catalogPath: options.catalogPath,
+          env,
+          homeDir: options.homeDir,
+          io,
+          now,
+          storageFactory,
+        });
+      case "share":
+      case "sh":
+        return await runShare(parsed, {
+          catalogPath: options.catalogPath,
+          env,
+          homeDir: options.homeDir,
+          io,
+          storageFactory,
+        });
+      case "status":
+      case "st":
+        return await runStatus(parsed, {
+          catalogPath: options.catalogPath,
+          env,
+          homeDir: options.homeDir,
+          io,
+          storageFactory,
+        });
+      default:
+        throw new Error(`unknown command ${parsed.command}`);
+    }
+  } catch (error) {
+    emitError(io, "cli", getErrorMessage(error));
+    return 1;
+  }
+}
+
+async function runList(
+  parsed: ParsedArgs,
+  options: { catalogPath?: string; env: EnvMap; homeDir?: string; io: CliIo },
+): Promise<number> {
+  if (parsed.positionals.length > 1) {
+    throw new Error("list accepts at most one prefix");
+  }
+
+  const config = requireCoreConfig(options.env, {
+    catalogPath: options.catalogPath,
+    homeDir: options.homeDir,
+  });
+
+  const catalog = new Catalog(config.catalogPath);
+  try {
+    const objects = catalog.listObjects(config.bucket, parsed.positionals[0]);
+    if (parsed.flags.json) {
+      emitJson(options.io, { bucket: config.bucket, objects });
+      return 0;
+    }
+
+    for (const object of objects) {
+      options.io.stdout(
+        `${object.key}\t${object.visibility}\t${object.size}\t${formatTimestamp(object.uploadedAt)}`,
+      );
+    }
+    return 0;
+  } finally {
+    catalog.close();
+  }
+}
+
+async function runUpload(
+  parsed: ParsedArgs,
+  options: {
+    catalogPath?: string;
+    cwd: string;
+    env: EnvMap;
+    homeDir?: string;
+    io: CliIo;
+    now: () => Date;
+    storageFactory: (config: AppConfig) => StorageClient;
+  },
+): Promise<number> {
+  const visibility = resolveVisibility(parsed.flags);
+  const prefix = readOptionalStringFlag(parsed.flags, "prefix");
+  const config = requireCoreConfig(options.env, {
+    catalogPath: options.catalogPath,
+    homeDir: options.homeDir,
+  });
+
+  if (visibility === "public") {
+    ensurePublicBaseUrl(config);
+  }
+
+  const uploadTargets = await resolveUploadTargets(parsed.positionals, {
+    cwd: options.cwd,
+    prefix,
+  });
+
+  await mkdir(dirname(config.catalogPath), { recursive: true });
+  const storage = options.storageFactory(config);
+  const catalog = new Catalog(config.catalogPath);
+  const uploaded: Array<{ key: string; size: number; visibility: Visibility }> = [];
+
+  try {
+    for (const target of uploadTargets) {
+      const remoteMeta = await storage.uploadFile(target.absolutePath, target.key, visibility);
+      const uploadedAt = options.now().toISOString();
+      catalog.upsertObject({
+        bucket: config.bucket,
+        contentType: remoteMeta.contentType,
+        etag: remoteMeta.etag,
+        key: target.key,
+        size: remoteMeta.size,
+        sourcePath: target.sourcePath,
+        uploadedAt,
+        visibility,
+      });
+      uploaded.push({
+        key: target.key,
+        size: remoteMeta.size,
+        visibility,
+      });
+    }
+
+    if (parsed.flags.json) {
+      emitJson(options.io, { bucket: config.bucket, uploaded });
+      return 0;
+    }
+
+    for (const item of uploaded) {
+      options.io.stdout(`uploaded\t${item.key}\t${item.visibility}\t${item.size}`);
+    }
+    return 0;
+  } finally {
+    catalog.close();
+  }
+}
+
+async function runDelete(
+  parsed: ParsedArgs,
+  options: {
+    catalogPath?: string;
+    env: EnvMap;
+    homeDir?: string;
+    io: CliIo;
+    now: () => Date;
+    storageFactory: (config: AppConfig) => StorageClient;
+  },
+): Promise<number> {
+  if (parsed.positionals.length === 0) {
+    throw new Error("delete requires at least one key");
+  }
+
+  const config = requireCoreConfig(options.env, {
+    catalogPath: options.catalogPath,
+    homeDir: options.homeDir,
+  });
+  const storage = options.storageFactory(config);
+  const catalog = new Catalog(config.catalogPath);
+  const deleted: string[] = [];
+  const errors: Array<{ key: string; message: string }> = [];
+
+  try {
+    for (const key of parsed.positionals) {
+      const tracked = catalog.getObject(config.bucket, key);
+      if (!tracked) {
+        const message = `untracked key ${key}`;
+        errors.push({ key, message });
+        if (!parsed.flags.json) {
+          emitError(options.io, "delete", message);
+        }
+        continue;
+      }
+
+      try {
+        await storage.deleteObject(key);
+        catalog.softDeleteObject(config.bucket, key, options.now().toISOString());
+        deleted.push(key);
+      } catch (error) {
+        const message = `${key} ${getErrorMessage(error)}`;
+        errors.push({ key, message });
+        if (!parsed.flags.json) {
+          emitError(options.io, "delete", message);
+        }
+      }
+    }
+
+    if (parsed.flags.json) {
+      emitJson(options.io, { bucket: config.bucket, deleted, errors });
+    } else {
+      for (const key of deleted) {
+        options.io.stdout(`deleted\t${key}`);
+      }
+    }
+
+    return errors.length === 0 ? 0 : 1;
+  } finally {
+    catalog.close();
+  }
+}
+
+async function runShare(
+  parsed: ParsedArgs,
+  options: {
+    catalogPath?: string;
+    env: EnvMap;
+    homeDir?: string;
+    io: CliIo;
+    storageFactory: (config: AppConfig) => StorageClient;
+  },
+): Promise<number> {
+  if (parsed.positionals.length !== 1) {
+    throw new Error("share requires exactly one key");
+  }
+
+  const config = requireCoreConfig(options.env, {
+    catalogPath: options.catalogPath,
+    homeDir: options.homeDir,
+  });
+  const catalog = new Catalog(config.catalogPath);
+  try {
+    const key = parsed.positionals[0]!;
+    const tracked = catalog.getObject(config.bucket, key);
+    if (!tracked) {
+      throw new Error(`untracked key ${key}`);
+    }
+
+    if (tracked.visibility === "public") {
+      ensurePublicBaseUrl(config);
+    }
+
+    const expiresIn = readOptionalPositiveIntegerFlag(parsed.flags, "expires") ?? config.shareTtlSeconds;
+    const storage = options.storageFactory(config);
+    const url = await storage.getShareUrl(key, tracked.visibility, expiresIn);
+
+    if (parsed.flags.json) {
+      emitJson(options.io, {
+        expiresIn: tracked.visibility === "private" ? expiresIn : null,
+        key,
+        url,
+        visibility: tracked.visibility,
+      });
+      return 0;
+    }
+
+    options.io.stdout(url);
+    return 0;
+  } finally {
+    catalog.close();
+  }
+}
+
+async function runStatus(
+  parsed: ParsedArgs,
+  options: {
+    catalogPath?: string;
+    env: EnvMap;
+    homeDir?: string;
+    io: CliIo;
+    storageFactory: (config: AppConfig) => StorageClient;
+  },
+): Promise<number> {
+  if (parsed.positionals.length > 0) {
+    throw new Error("status does not accept positional arguments");
+  }
+
+  const checks: StatusCheckResult[] = [];
+  const envChecks = inspectEnv(options.env);
+  const catalogPath = options.catalogPath ?? resolveCatalogPath(options.env, options.homeDir);
+
+  if (parsed.flags.json) {
+    for (const check of envChecks) {
+      checks.push({ message: check.message, name: check.key, ok: check.ok });
+    }
+  } else {
+    for (const check of envChecks) {
+      emitEnvCheck(options.io, check);
+    }
+  }
+
+  let dbOk = false;
+  try {
+    const catalog = new Catalog(catalogPath);
+    catalog.ping();
+    catalog.close();
+    dbOk = true;
+    if (parsed.flags.json) {
+      checks.push({ message: catalogPath, name: "db", ok: true });
+    } else {
+      options.io.stdout(`ok\tdb\t${catalogPath}`);
+    }
+  } catch (error) {
+    const message = getErrorMessage(error);
+    if (parsed.flags.json) {
+      checks.push({ message, name: "db", ok: false });
+    } else {
+      emitError(options.io, "db", message);
+    }
+  }
+
+  let config: AppConfig | null = null;
+  try {
+    config = requireCoreConfig(options.env, {
+      catalogPath: options.catalogPath,
+      homeDir: options.homeDir,
+    });
+  } catch (error) {
+    if (parsed.flags.json) {
+      checks.push({ message: getErrorMessage(error), name: "core_config", ok: false });
+      emitJson(options.io, {
+        checks,
+        ready: false,
+        requiredEnv: getReadyEnvKeys(),
+      });
+      return 1;
+    }
+
+    options.io.stdout("not_ready");
+    return 1;
+  }
+
+  let s3Ok = false;
+  try {
+    const storage = options.storageFactory(config);
+    await storage.probe();
+    s3Ok = true;
+    if (parsed.flags.json) {
+      checks.push({ message: config.bucket, name: "s3", ok: true });
+    } else {
+      options.io.stdout(`ok\ts3\t${config.bucket}`);
+    }
+  } catch (error) {
+    const message = getErrorMessage(error);
+    if (parsed.flags.json) {
+      checks.push({ message, name: "s3", ok: false });
+    } else {
+      emitError(options.io, "s3", message);
+    }
+  }
+
+  const ready = envChecks.every((check) => check.ok) && dbOk && s3Ok;
+  if (parsed.flags.json) {
+    emitJson(options.io, {
+      checks,
+      ready,
+      requiredEnv: getReadyEnvKeys(),
+    });
+  } else {
+    options.io.stdout(ready ? "ready" : "not_ready");
+  }
+
+  return ready ? 0 : 1;
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const flags: Record<string, string | boolean> = {};
+  const positionals: string[] = [];
+  let command: string | null = null;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === undefined) {
+      continue;
+    }
+
+    if (!command && !token.startsWith("-")) {
+      command = token;
+      continue;
+    }
+
+    if (token === "--json") {
+      flags.json = true;
+      continue;
+    }
+
+    if (token === "--help" || token === "-h") {
+      flags.help = true;
+      continue;
+    }
+
+    if (token === "--public") {
+      flags.public = true;
+      continue;
+    }
+
+    if (token === "--private") {
+      flags.private = true;
+      continue;
+    }
+
+    if (token === "--prefix" || token === "--expires") {
+      const nextValue = argv[index + 1];
+      if (nextValue === undefined || nextValue.startsWith("-")) {
+        throw new Error(`missing value for ${token}`);
+      }
+      flags[token.slice(2)] = nextValue;
+      index += 1;
+      continue;
+    }
+
+    if (token.startsWith("--")) {
+      throw new Error(`unknown flag ${token}`);
+    }
+
+    positionals.push(token);
+  }
+
+  return { command, flags, positionals };
+}
+
+function resolveVisibility(flags: Record<string, string | boolean>): Visibility {
+  if (flags.public && flags.private) {
+    throw new Error("choose either --public or --private");
+  }
+
+  return flags.public ? "public" : "private";
+}
+
+function readOptionalStringFlag(flags: Record<string, string | boolean>, key: string): string | undefined {
+  const value = flags[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+function readOptionalPositiveIntegerFlag(
+  flags: Record<string, string | boolean>,
+  key: string,
+): number | undefined {
+  const value = readOptionalStringFlag(flags, key);
+  if (!value) {
+    return undefined;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`invalid ${key} ${value}`);
+  }
+
+  return parsed;
+}
+
+function printHelp(io: CliIo): void {
+  io.stdout("s3-storage-cli");
+  io.stdout("status [--json]");
+  io.stdout("list|ls [prefix] [--json]");
+  io.stdout("upload|up <paths...> [--public|--private] [--prefix <remote-prefix>] [--json]");
+  io.stdout("delete|rm <keys...> [--json]");
+  io.stdout("share|sh <key> [--expires <seconds>] [--json]");
+}
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+}

package/src/config.ts

@@ -0,0 +1,126 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export type EnvMap = Record<string, string | undefined>;
+
+export type Visibility = "private" | "public";
+
+export interface AppConfig {
+  accessKeyId: string;
+  bucket: string;
+  catalogPath: string;
+  endpoint: string;
+  publicBaseUrl?: string;
+  region: string;
+  secretAccessKey: string;
+  sessionToken?: string;
+  shareTtlSeconds: number;
+  virtualHostedStyle: boolean;
+}
+
+export interface EnvCheck {
+  key: string;
+  ok: boolean;
+  requiredForReady: boolean;
+  message?: string;
+}
+
+const CORE_ENV_KEYS = [
+  "S3_ENDPOINT",
+  "S3_REGION",
+  "S3_ACCESS_KEY_ID",
+  "S3_SECRET_ACCESS_KEY",
+  "S3_BUCKET",
+] as const;
+
+const READY_ENV_KEYS = [...CORE_ENV_KEYS, "S3_PUBLIC_BASE_URL"] as const;
+
+export function getReadyEnvKeys(): readonly string[] {
+  return READY_ENV_KEYS;
+}
+
+export function inspectEnv(env: EnvMap): EnvCheck[] {
+  return READY_ENV_KEYS.map((key) => {
+    const value = env[key];
+    return {
+      key,
+      ok: Boolean(value && value.trim()),
+      requiredForReady: true,
+      message: value && value.trim() ? undefined : `missing ${key}`,
+    };
+  });
+}
+
+export function getMissingCoreEnvKeys(env: EnvMap): string[] {
+  return CORE_ENV_KEYS.filter((key) => !env[key]?.trim());
+}
+
+export function requireCoreConfig(
+  env: EnvMap,
+  options: { homeDir?: string; catalogPath?: string } = {},
+): AppConfig {
+  const missing = getMissingCoreEnvKeys(env);
+  if (missing.length > 0) {
+    throw new Error(`missing env ${missing.join(",")}`);
+  }
+
+  return {
+    accessKeyId: env.S3_ACCESS_KEY_ID!.trim(),
+    bucket: env.S3_BUCKET!.trim(),
+    catalogPath: options.catalogPath ?? resolveCatalogPath(env, options.homeDir),
+    endpoint: env.S3_ENDPOINT!.trim(),
+    publicBaseUrl: env.S3_PUBLIC_BASE_URL?.trim() || undefined,
+    region: env.S3_REGION!.trim(),
+    secretAccessKey: env.S3_SECRET_ACCESS_KEY!.trim(),
+    sessionToken: env.S3_SESSION_TOKEN?.trim() || undefined,
+    shareTtlSeconds: parsePositiveInteger(env.S3_SHARE_TTL_SECONDS, 3600, "S3_SHARE_TTL_SECONDS"),
+    virtualHostedStyle: parseBoolean(env.S3_VIRTUAL_HOSTED_STYLE, false),
+  };
+}
+
+export function resolveCatalogPath(env: EnvMap, customHomeDir?: string): string {
+  const override = env.S3_CLI_DB_PATH?.trim();
+  if (override) {
+    return override;
+  }
+
+  return join(customHomeDir ?? homedir(), ".s3-storage-cli", "catalog.sqlite");
+}
+
+export function ensurePublicBaseUrl(config: AppConfig): string {
+  if (!config.publicBaseUrl) {
+    throw new Error("missing env S3_PUBLIC_BASE_URL");
+  }
+
+  return config.publicBaseUrl;
+}
+
+function parsePositiveInteger(raw: string | undefined, fallback: number, key: string): number {
+  if (!raw?.trim()) {
+    return fallback;
+  }
+
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`invalid env ${key}`);
+  }
+
+  return parsed;
+}
+
+function parseBoolean(raw: string | undefined, fallback: boolean): boolean {
+  if (!raw?.trim()) {
+    return fallback;
+  }
+
+  const normalized = raw.trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) {
+    return true;
+  }
+
+  if (["0", "false", "no", "off"].includes(normalized)) {
+    return false;
+  }
+
+  return fallback;
+}

package/src/files.ts

@@ -0,0 +1,101 @@
+import { lstat, readdir } from "node:fs/promises";
+import { basename, posix, relative, resolve } from "node:path";
+
+export interface UploadTarget {
+  absolutePath: string;
+  key: string;
+  sourcePath: string;
+}
+
+export async function resolveUploadTargets(
+  inputPaths: string[],
+  options: { cwd: string; prefix?: string },
+): Promise<UploadTarget[]> {
+  if (inputPaths.length === 0) {
+    throw new Error("upload requires at least one path");
+  }
+
+  const prefix = normalizePrefix(options.prefix);
+  const targets: UploadTarget[] = [];
+
+  for (const inputPath of inputPaths) {
+    const absoluteInputPath = resolve(options.cwd, inputPath);
+    const stats = await lstat(absoluteInputPath).catch(() => null);
+    if (!stats) {
+      throw new Error(`path not found ${inputPath}`);
+    }
+
+    if (stats.isDirectory()) {
+      const directoryName = basename(absoluteInputPath);
+      const entries = await walkDirectory(absoluteInputPath);
+      for (const filePath of entries) {
+        const relativeInsideDirectory = toS3Key(relative(absoluteInputPath, filePath));
+        targets.push({
+          absolutePath: filePath,
+          key: `${prefix}${toS3Key(posix.join(directoryName, relativeInsideDirectory))}`,
+          sourcePath: filePath,
+        });
+      }
+      continue;
+    }
+
+    if (!stats.isFile()) {
+      throw new Error(`unsupported path ${inputPath}`);
+    }
+
+    targets.push({
+      absolutePath: absoluteInputPath,
+      key: `${prefix}${toS3Key(basename(absoluteInputPath))}`,
+      sourcePath: absoluteInputPath,
+    });
+  }
+
+  if (targets.length === 0) {
+    throw new Error("no files found");
+  }
+
+  assertNoDuplicateKeys(targets);
+  return targets;
+}
+
+function normalizePrefix(prefix: string | undefined): string {
+  if (!prefix?.trim()) {
+    return "";
+  }
+
+  return toS3Key(prefix.trim()).replace(/^\/+/, "").replace(/\/?$/, "/");
+}
+
+function toS3Key(value: string): string {
+  return value.replaceAll("\\", "/").replace(/^\/+/, "");
+}
+
+async function walkDirectory(directoryPath: string): Promise<string[]> {
+  const entries = await readdir(directoryPath, { withFileTypes: true });
+  const files: string[] = [];
+
+  for (const entry of entries) {
+    const entryPath = resolve(directoryPath, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await walkDirectory(entryPath)));
+      continue;
+    }
+
+    if (entry.isFile()) {
+      files.push(entryPath);
+    }
+  }
+
+  return files.sort((left, right) => left.localeCompare(right));
+}
+
+function assertNoDuplicateKeys(targets: UploadTarget[]): void {
+  const seen = new Map<string, string>();
+  for (const target of targets) {
+    const previous = seen.get(target.key);
+    if (previous) {
+      throw new Error(`duplicate key ${target.key} from ${previous} and ${target.sourcePath}`);
+    }
+    seen.set(target.key, target.sourcePath);
+  }
+}

package/src/output.ts

@@ -0,0 +1,34 @@
+import type { EnvCheck } from "./config";
+
+export interface CliIo {
+  stderr: (line: string) => void;
+  stdout: (line: string) => void;
+}
+
+export function createDefaultIo(): CliIo {
+  return {
+    stderr: (line) => process.stderr.write(`${line}\n`),
+    stdout: (line) => process.stdout.write(`${line}\n`),
+  };
+}
+
+export function emitJson(io: CliIo, data: unknown): void {
+  io.stdout(JSON.stringify(data));
+}
+
+export function emitError(io: CliIo, code: string, message: string): void {
+  io.stderr(`error\t${code}\t${message}`);
+}
+
+export function emitEnvCheck(io: CliIo, check: EnvCheck): void {
+  if (check.ok) {
+    io.stdout(`ok\tenv\t${check.key}`);
+    return;
+  }
+
+  emitError(io, "env", check.message ?? `invalid ${check.key}`);
+}
+
+export function formatTimestamp(value: string): string {
+  return new Date(value).toISOString();
+}

package/src/storage.ts

@@ -0,0 +1,85 @@
+import { S3Client } from "bun";
+import type { AppConfig, Visibility } from "./config";
+
+export interface UploadedRemoteMeta {
+  contentType: string | null;
+  etag: string | null;
+  size: number;
+}
+
+export interface StorageClient {
+  deleteObject(key: string): Promise<void>;
+  getShareUrl(key: string, visibility: Visibility, expiresIn: number): Promise<string>;
+  probe(): Promise<void>;
+  uploadFile(localPath: string, key: string, visibility: Visibility): Promise<UploadedRemoteMeta>;
+}
+
+export class BunStorageClient implements StorageClient {
+  private readonly client: S3Client;
+  private readonly config: AppConfig;
+
+  constructor(config: AppConfig) {
+    this.config = config;
+    this.client = new S3Client({
+      accessKeyId: config.accessKeyId,
+      bucket: config.bucket,
+      endpoint: config.endpoint,
+      region: config.region,
+      secretAccessKey: config.secretAccessKey,
+      sessionToken: config.sessionToken,
+      virtualHostedStyle: config.virtualHostedStyle,
+    });
+  }
+
+  async deleteObject(key: string): Promise<void> {
+    await this.client.delete(key);
+  }
+
+  async getShareUrl(key: string, visibility: Visibility, expiresIn: number): Promise<string> {
+    if (visibility === "public") {
+      if (!this.config.publicBaseUrl) {
+        throw new Error("missing env S3_PUBLIC_BASE_URL");
+      }
+
+      return buildPublicObjectUrl(this.config.publicBaseUrl, key);
+    }
+
+    return this.client.presign(key, {
+      expiresIn,
+      method: "GET",
+    });
+  }
+
+  async probe(): Promise<void> {
+    const probeKey = "__s3_storage_cli_status_probe__";
+    await this.client.exists(probeKey);
+  }
+
+  async uploadFile(localPath: string, key: string, visibility: Visibility): Promise<UploadedRemoteMeta> {
+    const file = Bun.file(localPath);
+    const localType = file.type || undefined;
+    await this.client.write(key, file, {
+      acl: visibility === "public" ? "public-read" : "private",
+      type: localType,
+    });
+
+    const remote = await this.client.stat(key);
+    return {
+      contentType: remote.type || localType || null,
+      etag: remote.etag || null,
+      size: remote.size,
+    };
+  }
+}
+
+export function buildPublicObjectUrl(baseUrl: string, key: string): string {
+  const url = new URL(baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
+  const encodedKey = key
+    .split("/")
+    .filter(Boolean)
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+  const basePath = url.pathname.endsWith("/") ? url.pathname : `${url.pathname}/`;
+  url.pathname = `${basePath}${encodedKey}`.replace(/\/+/g, "/");
+  return url.toString();
+}