@chidchanun/bcp 0.1.26 → 0.1.27

package/docs/README.md

@@ -2,9 +2,9 @@
 
 The `docs/` directory is the documentation source of truth for BCP Framework and is intentionally organized for the future **`bcp-docs-web`** website.
 
-> **Documentation target:** BCP Framework `0.1.26`
+> **Documentation target:** BCP Framework `0.1.27`
 >
-> **Release state:** release-candidate source. Do not label `0.1.26` as published until RC validation and npm publication complete.
+> **Release state:** unreleased development target. Do not label `0.1.27` as published until RC validation and npm publication complete.
 
 ## Documentation flow
 
@@ -95,7 +95,8 @@ Releases
 | --- | --- | --- |
 | `/docs/file-upload` | `file-upload.md` | Buffered + streaming multipart uploads |
 | `/docs/storage` | `storage.md` | StorageAdapter, streaming and file delivery |
-| `/docs/s3-storage` | `s3-storage.md` | S3-compatible adapter/configuration |
+| `/docs/storage-ecosystem` | `storage-ecosystem.md` | Listing, copy/move, metadata, bulk delete, signed URLs |
+| `/docs/s3-storage` | `s3-storage.md` | S3/R2/MinIO adapter and direct object access |
 
 ## API Reference ownership
 
@@ -116,7 +117,7 @@ bcp/middleware
 | Entrypoint | Primary guide |
 | --- | --- |
 | `bcp` | `routing.md`, `server-data-loaders.md`, `form-actions.md` |
-| `bcp/server` | `server-request-apis.md`, `file-upload.md`, `storage.md`, `s3-storage.md`, `development-logging.md` |
+| `bcp/server` | `server-request-apis.md`, `file-upload.md`, `storage.md`, `storage-ecosystem.md`, `s3-storage.md`, `development-logging.md` |
 | `bcp/auth` | `authentication.md`, `auth-route-guards.md` |
 | `bcp/database` | `database.md`, `database-migrations.md` |
 | `bcp/validation` | `validation.md` |
@@ -151,13 +152,17 @@ bcp/middleware
 
 - buffered multipart `FormData` upload APIs
 - production streaming multipart upload (`storeMultipartFile()`)
-- `StorageAdapter` contract
-- local filesystem adapter
-- S3-compatible adapter
-- streaming reads/writes
-- byte ranges
+- backward-compatible `StorageAdapter` contract
+- local filesystem storage
+- S3/R2/MinIO-compatible storage
+- streaming reads/writes and byte ranges
 - ETag/Last-Modified file delivery
 - upload/storage limits and abort cleanup
+- object listing with cursors
+- native/fallback copy and move
+- portable user metadata
+- bulk deletion
+- S3 presigned read/write URLs
 
 ### Database
 
@@ -177,64 +182,66 @@ bcp/middleware
 - standalone production build
 - unit/integration/E2E/package/RC checks
 
-## BCP 0.1.26 documentation focus
+## BCP 0.1.27 documentation focus
 
-### Storage streaming
+### Storage ecosystem
 
-Public additions include:
+New generic helpers include:
 
 ```ts
 import {
-    getStorageCapabilities,
-    putStorageStream,
-    readStorageStream,
+    copyStorageObject,
+    createStorageSignedReadUrl,
+    createStorageSignedWriteUrl,
+    deleteStorageObjects,
+    getStorageEcosystemCapabilities,
+    getStorageMetadata,
+    listStorageObjects,
+    moveStorageObject,
+    setStorageMetadata,
 } from "bcp/server";
 ```
 
-Streaming methods remain optional on custom adapters for `0.1.25` compatibility.
+Document these boundaries clearly:
 
-### S3-compatible storage
+- ecosystem methods are additive and do not invalidate older `StorageAdapter` implementations,
+- listing cursors are opaque,
+- overwrite remains opt-in,
+- move is copy + delete rather than an atomic distributed transaction,
+- application metadata is portable string metadata and not authorization/business state,
+- `bcp_sha256` is reserved for framework checksum metadata,
+- local storage does not emulate signed URLs,
+- S3 direct-transfer URLs are temporary credentials and require application authorization before issuance.
 
-```ts
-import {
-    createS3Storage,
-} from "bcp/server";
-```
+See `storage-ecosystem.md`.
 
-Document:
+### S3 ecosystem
 
-- bucket/region/endpoint setup,
-- optional explicit credentials,
-- AWS default credential chain behavior,
-- `forcePathStyle` for compatible services such as MinIO,
-- prefix handling,
-- multipart streaming,
-- ranges/ETag metadata,
-- overwrite limitations for concurrent multipart writers,
-- server-only credential/security requirements.
+`createS3Storage()` keeps the same public constructor and now adds:
 
-See `s3-storage.md`.
+```text
+ListObjectsV2
+CopyObject
+DeleteObjects
+presigned GetObject
+presigned PutObject
+application metadata
+```
 
-### Production multipart streaming
+See `s3-storage.md`.
 
-```ts
-import {
-    storeMultipartFile,
-} from "bcp/server";
-```
+### 0.1.26 foundations remain supported
 
-Document:
+The following remain part of the storage stack:
 
-- one named streamed file field per operation,
-- total request limit,
-- per-file limit,
-- MIME/extension validation,
-- fixed/callback storage keys,
-- AbortSignal behavior,
-- direct local/S3 streaming,
-- difference from `request.formData()` / buffered APIs.
+```text
+putStorageStream()
+readStorageStream()
+storeMultipartFile()
+createStorageResponse()
+```
 
-See `file-upload.md`.
+`0.1.27` builds on these rather than replacing them.
 
 ## CLI commands
 
@@ -278,6 +285,7 @@ docs/releases/
 Recommended routes:
 
 ```text
+/releases/0.1.27
 /releases/0.1.26
 /releases/0.1.25
 /releases/0.1.24
@@ -357,15 +365,16 @@ npm run test:package
 npm run rc:check
 ```
 
-For `0.1.26`, package validation must also confirm the staged npm artifact contains:
+For `0.1.27`, package validation must also confirm the staged artifact includes:
 
 ```text
 @aws-sdk/client-s3
 @aws-sdk/lib-storage
+@aws-sdk/s3-request-presigner
 busboy
 ```
 
-and the S3/multipart streaming source files/public exports.
+and the ecosystem runtime/public exports.
 
 ## Documentation QA checklist
 
@@ -377,19 +386,22 @@ and the S3/multipart streaming source files/public exports.
 - route names match the current router,
 - release notes match the framework version,
 - S3 credentials are never shown as public browser variables,
+- signed URLs are documented as temporary credentials,
 - roadmap APIs are not presented as published guarantees.
 
-## Next direction after 0.1.26
+## Next direction after 0.1.27
 
-Recommended `0.1.27` direction:
+Planned `0.1.28 — Production Hardening` focus:
 
-- signed URLs where needed,
-- object listing/copy/move capabilities,
-- broader production hardening,
-- graceful shutdown/resource cleanup,
-- stronger storage/provider diagnostics.
+- graceful HTTP shutdown and active-request draining,
+- database/S3 resource cleanup,
+- trusted proxy and forwarded-header handling,
+- timeout controls,
+- security hardening,
+- Docker/standalone runtime regression coverage,
+- startup/runtime dependency diagnostics.
 
-These are roadmap items, not `0.1.26` guarantees.
+These remain roadmap items until their source/tests land.
 
 ## Repository authority
 

package/docs/releases/0.1.27.md

@@ -0,0 +1,350 @@
+# BCP Framework 0.1.27
+
+BCP Framework `0.1.27` is the **Storage Ecosystem** milestone.
+
+> Release state: unreleased development target until local validation, RC checks, tagging and npm publication complete.
+
+## Highlights
+
+- Added object listing with prefix filtering, limits and opaque cursors.
+- Added generic and native copy/move operations.
+- Added application user metadata for local and S3-compatible storage.
+- Added bulk deletion helpers.
+- Added S3 presigned read and write URLs.
+- Expanded storage capability discovery without breaking the `0.1.26` `StorageAdapter` contract.
+- Preserved fallback copy/move/delete-many behavior for older custom adapters.
+- Added `create-bcp-app` storage provider selection for Local Server, Amazon S3 and Cloudflare R2.
+- Added provider-specific `lib/storage.ts` scaffolding and `.env.example` configuration.
+- Added local storage ecosystem unit coverage.
+- Added S3-compatible ecosystem integration coverage.
+- Extended packed-package smoke checks for the new runtime and presigner dependency.
+
+## Public API additions
+
+All new application APIs are available through `bcp/server`:
+
+```ts
+import {
+    copyStorageObject,
+    createStorageSignedReadUrl,
+    createStorageSignedWriteUrl,
+    deleteStorageObjects,
+    getStorageEcosystemCapabilities,
+    getStorageMetadata,
+    listStorageObjects,
+    moveStorageObject,
+    setStorageMetadata,
+} from "bcp/server";
+```
+
+New public types include:
+
+```text
+StorageEcosystemAdapter
+StorageEcosystemCapabilities
+StorageEcosystemPutOptions
+StorageEcosystemPutStreamOptions
+StorageListOptions
+StorageListResult
+StorageCopyOptions
+StorageDeleteManyResult
+StorageSignedUrlOptions
+StorageSignedWriteUrlOptions
+StorageUserMetadata
+S3StorageEcosystemAdapter
+```
+
+## Backward compatibility
+
+The original `StorageAdapter` remains valid. Ecosystem methods are additive and optional.
+
+Generic helpers select a native adapter method when available. Operations that can be implemented portably, such as copy/move/delete-many, also have compatibility fallbacks where practical.
+
+Custom `0.1.25` / `0.1.26` adapters therefore do not need to implement all `0.1.27` methods immediately.
+
+## create-bcp-app storage provider selection
+
+Interactive project creation now includes:
+
+```text
+Select storage provider:
+  None
+  Local Server
+  Amazon S3
+  Cloudflare R2
+```
+
+The same choices can be automated:
+
+```bash
+npx create-bcp-app my-app --storage local
+npx create-bcp-app my-app --storage amazon-s3
+npx create-bcp-app my-app --storage cloudflare-r2
+```
+
+Supported flag values are:
+
+```text
+none
+local
+amazon-s3
+cloudflare-r2
+```
+
+Selecting a provider creates `lib/storage.ts` and appends provider-specific settings to `.env.example`.
+
+### Local Server preset
+
+```dotenv
+STORAGE_LOCAL_DIRECTORY=./storage
+```
+
+The generated helper uses `createLocalStorage()` and adds `storage/` to `.gitignore`.
+
+### Amazon S3 preset
+
+```dotenv
+AWS_S3_BUCKET=
+AWS_REGION=ap-southeast-1
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_SESSION_TOKEN=
+AWS_S3_PREFIX=
+```
+
+The generated helper uses `createS3Storage()`. Explicit credentials are optional when the application deployment uses the AWS SDK server-side credential provider chain.
+
+### Cloudflare R2 preset
+
+```dotenv
+R2_ACCOUNT_ID=
+R2_BUCKET=
+R2_ACCESS_KEY_ID=
+R2_SECRET_ACCESS_KEY=
+R2_PREFIX=
+```
+
+The generated helper uses the S3-compatible adapter with `region: "auto"` and the Cloudflare account endpoint.
+
+All generated storage credentials remain server-only and must not be moved into `BCP_PUBLIC_*` environment variables.
+
+## Listing
+
+```ts
+const page =
+    await listStorageObjects(
+        storage,
+        {
+            prefix: "documents/",
+            limit: 50,
+        }
+    );
+```
+
+The result contains:
+
+```ts
+{
+    objects: StorageObjectMetadata[];
+    cursor?: string;
+}
+```
+
+Cursors are opaque. Applications should pass them back unchanged rather than decoding or constructing them.
+
+The built-in local adapter uses a stable key-order cursor. The S3 adapter maps the generic cursor to the provider continuation token.
+
+## Copy and move
+
+```ts
+await copyStorageObject(
+    storage,
+    "incoming/report.pdf",
+    "archive/report.pdf"
+);
+
+await moveStorageObject(
+    storage,
+    "incoming/avatar.webp",
+    "users/42/avatar.webp"
+);
+```
+
+S3 uses native `CopyObject`. Other adapters can fall back to streamed read/write copy behavior.
+
+Overwrite remains opt-in.
+
+## User metadata
+
+`0.1.27` adds portable string metadata separate from BCP's internal checksum metadata:
+
+```ts
+await storage.put(
+    "documents/report.pdf",
+    bytes,
+    {
+        contentType: "application/pdf",
+        metadata: {
+            owner: "user-42",
+            category: "report",
+        },
+    }
+);
+```
+
+Read or replace metadata independently:
+
+```ts
+const metadata =
+    await getStorageMetadata(
+        storage,
+        "documents/report.pdf"
+    );
+
+await setStorageMetadata(
+    storage,
+    "documents/report.pdf",
+    {
+        owner: "user-42",
+        state: "approved",
+    }
+);
+```
+
+Metadata keys are normalized to lowercase and must use portable storage-safe characters. The reserved `bcp_sha256` key cannot be set by applications.
+
+## Bulk deletion
+
+```ts
+const result =
+    await deleteStorageObjects(
+        storage,
+        [
+            "tmp/a.bin",
+            "tmp/b.bin",
+        ]
+    );
+```
+
+The result contains:
+
+```ts
+{
+    deleted: string[];
+    missing: string[];
+    failed: Array<{
+        key: string;
+        message: string;
+    }>;
+}
+```
+
+S3 deletion semantics treat deletion of a missing object as successful, so S3 normally reports those keys under `deleted` rather than `missing`.
+
+## Presigned URLs
+
+S3-compatible adapters expose direct read/write signing:
+
+```ts
+const downloadUrl =
+    await createStorageSignedReadUrl(
+        storage,
+        "videos/demo.mp4",
+        {
+            expiresIn: 300,
+        }
+    );
+
+const uploadUrl =
+    await createStorageSignedWriteUrl(
+        storage,
+        "uploads/demo.mp4",
+        {
+            expiresIn: 300,
+            contentType: "video/mp4",
+        }
+    );
+```
+
+Signed URLs are useful when browsers or other clients should transfer large files directly with object storage rather than proxying bytes through the application server.
+
+The default expiry is 15 minutes. `expiresIn` is limited to the S3 SigV4 maximum of seven days.
+
+Local filesystem storage intentionally does not emulate signed URLs.
+
+## Capabilities
+
+Use:
+
+```ts
+getStorageEcosystemCapabilities(storage)
+```
+
+The extended capability result includes:
+
+```ts
+{
+    streamingRead,
+    streamingWrite,
+    ranges,
+    signedUrls,
+    listing,
+    signedReadUrls,
+    signedWriteUrls,
+    copy,
+    move,
+    metadata,
+    bulkDelete,
+}
+```
+
+For the built-in S3 ecosystem adapter all of these capabilities are enabled.
+
+For local storage, listing/copy/move/metadata/bulk-delete are enabled while signed URL capabilities remain disabled.
+
+## Dependency change
+
+The framework package adds:
+
+```text
+@aws-sdk/s3-request-presigner
+```
+
+alongside the S3 client and multipart upload dependencies introduced in `0.1.26`.
+
+## Testing
+
+`0.1.27` adds regression coverage for:
+
+- local listing and pagination,
+- portable metadata,
+- metadata preservation during copy/move,
+- bulk deletion,
+- unsupported local signed URLs,
+- S3 listing,
+- S3 native copy/move,
+- S3 metadata replacement,
+- S3 bulk deletion,
+- S3 signed read/write URL generation,
+- create-app Local Server storage scaffolding,
+- create-app Amazon S3 storage scaffolding,
+- create-app Cloudflare R2 storage scaffolding,
+- non-interactive `--storage` CLI selection,
+- public package exports,
+- packed dependency/runtime presence.
+
+## Remaining release work
+
+Before publication:
+
+1. sync `package-lock.json` with `0.1.27` and the presigner dependency,
+2. run `npm run typecheck`,
+3. run unit/integration/E2E/package tests,
+4. run `npm run rc:check`,
+5. validate a packed `0.1.27` package in a representative application,
+6. create the `v0.1.27` tag only after the final release commit is known,
+7. publish and verify npm visibility.
+
+## Next milestone
+
+The planned next milestone is `0.1.28 — Production Hardening`, focused on graceful shutdown, proxy awareness, timeouts, security and Docker/standalone runtime reliability.