s3-ship 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 s3-ship contributors
+
+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,196 @@
+# s3-ship
+
+[![npm version](https://img.shields.io/npm/v/s3-ship.svg)](https://www.npmjs.com/package/s3-ship)
+[![npm downloads](https://img.shields.io/npm/dm/s3-ship.svg)](https://www.npmjs.com/package/s3-ship)
+[![CI](https://github.com/yfxie/s3-ship/actions/workflows/ci.yml/badge.svg)](https://github.com/yfxie/s3-ship/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/yfxie/s3-ship/branch/main/graph/badge.svg)](https://codecov.io/gh/yfxie/s3-ship)
+[![License](https://img.shields.io/npm/l/s3-ship.svg)](https://github.com/yfxie/s3-ship/blob/main/LICENSE)
+[![Types](https://img.shields.io/npm/types/s3-ship.svg)](https://www.npmjs.com/package/s3-ship)
+[![Built with Bun](https://img.shields.io/badge/built%20with-Bun-fbf0df)](https://bun.sh)
+
+Deploy a directory of static files to AWS S3 with redirects, CloudFront invalidation, and multi-environment support — in a single command.
+
+```sh
+npm install -g s3-ship
+s3-ship init
+# edit s3-ship.config.ts
+s3-ship deploy
+```
+
+## Features
+
+- **One-shot deploy** — scan local files, diff against S3 (by MD5/ETag), upload only what changed
+- **Redirects** — bulk-define `WebsiteRedirectLocation` redirect objects in config
+- **CloudFront invalidation** — automatically clear edge caches after upload
+- **Multi-environment** — separate buckets/distributions per `staging` / `production`
+- **AWS profile and env-var support** — works with your existing AWS credentials
+- **Dry-run** — preview every action before any network write
+- **Sync-delete (opt-in)** — remove S3 keys no longer present locally, **bounded to your target prefix**
+- **Smart ignore** — `.DS_Store`, `Thumbs.db`, `.git/`, `*.swp` are always excluded
+- **Multiple config formats** — auto-detects `.ts`, `.js`, `.mjs`, `.cjs`, `.json`, `.yml`, `.yaml`
+- **Fail-fast validation** — config errors are reported all at once before any AWS call
+
+## Install
+
+```sh
+# global
+npm install -g s3-ship
+
+# or per-project
+npm install --save-dev s3-ship
+```
+
+Requires Node.js 18+.
+
+## Quickstart
+
+1. Create a config file in your project root:
+
+```sh
+s3-ship init                    # writes s3-ship.config.ts
+s3-ship init --format json      # or json / yml / js / mjs
+```
+
+2. Edit the file:
+
+```ts
+import { defineConfig } from 's3-ship'
+
+export default defineConfig({
+  source: 'dist',
+  bucket: 'my-website-bucket',
+  region: 'us-east-1',
+  cloudfront: { distributionId: 'EABCDEF12345' },
+})
+```
+
+3. Preview, then deploy:
+
+```sh
+s3-ship deploy --dry-run
+s3-ship deploy
+```
+
+## Configuration
+
+Top-level options:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `source` | `string` | `'dist'` | Local directory to upload |
+| `target` | `string` | `''` | Target prefix in the bucket. All list/delete operations are bounded to this prefix |
+| `bucket` | `string` | — | S3 bucket name (required at top level or per environment) |
+| `region` | `string` | — | AWS region. Falls back to `AWS_REGION` env var |
+| `profile` | `string` | — | AWS profile name. Falls back to `AWS_PROFILE` env var |
+| `cloudfront` | `object` | — | `{ distributionId: string, invalidationPaths?: string[] }`. Default paths `['/*']` |
+| `syncDelete` | `boolean` | `false` | Delete remote keys not present locally (bounded to `target`) |
+| `ignore` | `string[]` | `[]` | Additional glob patterns to ignore on top of the always-ignored set |
+| `redirects` | `RedirectRule[]` | `[]` | See [Redirects](#redirects) below |
+| `cacheControl` | `CacheRule[]` | `[]` | Per-glob `Cache-Control` headers, e.g. `[{ match: 'assets/**', cacheControl: 'public, max-age=31536000, immutable' }]` |
+| `environments` | `Record<string, Partial<Config>>` | — | Named overrides; activated with `--env <name>` |
+
+### Multi-environment
+
+```ts
+export default defineConfig({
+  source: 'dist',
+  cloudfront: { invalidationPaths: ['/*'] }, // shared
+  environments: {
+    staging: {
+      bucket: 'staging.example.com',
+      cloudfront: { distributionId: 'ESTAGE' },
+    },
+    production: {
+      bucket: 'www.example.com',
+      cloudfront: { distributionId: 'EPROD' },
+    },
+  },
+})
+```
+
+```sh
+s3-ship deploy --env staging
+s3-ship deploy --env production
+```
+
+Precedence (high → low): **CLI flags > environment vars (`AWS_*`) > `environments.<name>` > top-level > built-in defaults**.
+
+### Redirects
+
+S3 supports per-object 301 redirects via `WebsiteRedirectLocation`. Each rule creates a 0-byte object whose only purpose is to redirect.
+
+```ts
+redirects: [
+  { from: 'blog/old-post', to: '/blog/new-post' },
+  { from: 'legacy.html', to: 'https://example.com', statusCode: 302 },
+]
+```
+
+- `from` is automatically prefixed by `target` if set.
+- If `from` collides with a real source file at the same key, the redirect wins — the source file is silently dropped from the upload plan.
+- Redirects are excluded from `syncDelete`.
+
+### Target prefix and sync-delete safety
+
+If `target = 'docs/v2'`, **every** S3 list and delete operation is bounded to `Prefix='docs/v2/'`. `syncDelete` will never touch a key outside this prefix, even if it's not in your local source.
+
+If `target` is empty (the bucket root), `syncDelete` operates on the whole bucket. Use with care.
+
+## CLI
+
+```
+s3-ship deploy [options]
+  --env <name>           Use environments.<name> from config
+  --profile <name>       Override AWS profile
+  --bucket <name>        Override target bucket
+  --target <prefix>      Override target prefix
+  --source <dir>         Override local source directory
+  --dry-run              Print plan, exit without uploading
+  --sync-delete          Enable sync-delete (overrides config)
+  --no-sync-delete       Disable sync-delete (overrides config)
+  --no-invalidate        Skip CloudFront invalidation
+  --config <path>        Path to config file
+  --verbose              List every file (uploads, updates, deletes, skipped, redirects, failures) without the default 20-item truncation
+
+s3-ship init [--format ts|js|mjs|json|yml|yaml]
+  Create a starter config file (default: ts)
+
+s3-ship validate [--config <path>]
+  Validate the config file without contacting AWS
+```
+
+Exit codes: `0` success — `1` config error — `2` AWS / upload failure.
+
+## Programmatic API
+
+```ts
+import { deploy } from 's3-ship'
+
+const result = await deploy({
+  cwd: process.cwd(),
+  envVars: process.env,
+  env: 'production',
+  dryRun: true,
+})
+console.log(result.plan)
+```
+
+`deploy()` returns `{ plan, report?, resolvedConfig, dryRun, configPath }`.
+
+## Development
+
+```sh
+bun install
+bun test                   # run tests
+bun test --watch           # watch mode
+bun run test:coverage      # generate coverage report (text + lcov)
+bun run typecheck
+bun run lint
+bun run build              # produces dist/
+```
+
+Coverage output is written to `coverage/lcov.info` for upload to Codecov in CI.
+
+## License
+
+MIT

package/dist/aws/cloudfront-client.d.ts

@@ -0,0 +1,10 @@
+import { CloudFrontClient } from '@aws-sdk/client-cloudfront';
+export interface CloudFrontLike {
+    send(command: unknown): Promise<unknown>;
+}
+export interface CloudFrontClientOptions {
+    region?: string;
+    profile?: string;
+}
+export declare function createCloudFrontClient(options: CloudFrontClientOptions): CloudFrontClient;
+//# sourceMappingURL=cloudfront-client.d.ts.map

package/dist/aws/cloudfront-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudfront-client.d.ts","sourceRoot":"","sources":["../../src/aws/cloudfront-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAG7D,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACzC;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,gBAAgB,CAKzF"}

package/dist/aws/s3-client.d.ts

@@ -0,0 +1,11 @@
+import { S3Client } from '@aws-sdk/client-s3';
+export interface S3Like {
+    send(command: unknown): Promise<unknown>;
+}
+export interface S3ClientOptions {
+    region?: string;
+    profile?: string;
+}
+export declare function createS3Client(options: S3ClientOptions): S3Client;
+export declare function normalizeTargetPrefix(target: string): string;
+//# sourceMappingURL=s3-client.d.ts.map

package/dist/aws/s3-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-client.d.ts","sourceRoot":"","sources":["../../src/aws/s3-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAG7C,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACzC;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,QAAQ,CAKjE;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAG5D"}

package/dist/cli/init.d.ts

@@ -0,0 +1,11 @@
+export type InitFormat = 'js' | 'ts' | 'mjs' | 'json' | 'yml' | 'yaml';
+export interface InitOptions {
+    cwd: string;
+    format?: InitFormat;
+}
+export interface InitResult {
+    path: string;
+    format: InitFormat;
+}
+export declare function initConfig(options: InitOptions): Promise<InitResult>;
+//# sourceMappingURL=init.d.ts.map

package/dist/cli/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAA;AAEtE,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,CAAC,EAAE,UAAU,CAAA;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,UAAU,CAAA;CACnB;AA4FD,wBAAsB,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAc1E"}

package/dist/cli/run.d.ts

@@ -0,0 +1,6 @@
+import { deploy } from '../deploy.js';
+export interface RunCliOptions {
+    deployFn?: typeof deploy;
+}
+export declare function runCli(argv: string[], options?: RunCliOptions): Promise<number>;
+//# sourceMappingURL=run.d.ts.map

package/dist/cli/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAoCrC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,OAAO,MAAM,CAAA;CACzB;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CA+FzF"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}